feat(dashboards): add the Heatmap chart

Assembles the pieces into the chart a panel mounts: bucket × time density grid,
where columns are time slices, rows are bucket ranges and cell colour is the
observation count — so a distribution can be watched changing shape instead of
collapsing to percentile lines.

It takes bucket bounds plus one series per group, the shape the query response
already has, and pivots and sums them itself rather than making every caller get
the transpose right. It builds its own `UPlotConfigBuilder`, since the y axis
*is* the bucket axis and the bounds fully determine it.

The group legend goes through the shared `Legend` — click a label to isolate a
group, a marker to exclude one — and the ColorBar mounts in the new content
footer as the scale key.

Panel kind, spec and the `heatmap` request type land separately.

Assisted-by: Claude Opus 5

.github/workflows/jsci.yaml

@@ -79,36 +79,6 @@ jobs:
         run: |
           cd frontend && pnpm generate:api
           git diff --compact-summary --exit-code || (echo; echo "Unexpected difference in generated api clients. Run pnpm generate:api in frontend/ locally and commit."; exit 1)
-  storybook:
-    if: |
-      github.event_name == 'merge_group' ||
-      (github.event_name == 'pull_request' && ! github.event.pull_request.head.repo.fork && github.event.pull_request.user.login != 'dependabot[bot]' && ! contains(github.event.pull_request.labels.*.name, 'safe-to-test')) ||
-      (github.event_name == 'pull_request_target' && contains(github.event.pull_request.labels.*.name, 'safe-to-test'))
-    runs-on: ubuntu-latest
-    timeout-minutes: 10
-    container:
-      image: mcr.microsoft.com/playwright:v1.57.0-noble
-    strategy:
-      fail-fast: false
-      matrix:
-        shard: [1, 2, 3, 4]
-    steps:
-      - name: self-checkout
-        uses: actions/checkout@v4
-      - name: install-pnpm
-        uses: pnpm/action-setup@v6
-        with:
-          version: 10
-      - name: node-install
-        uses: actions/setup-node@v5
-        with:
-          node-version: "22"
-          cache: pnpm
-          cache-dependency-path: frontend/pnpm-lock.yaml
-      - name: install-frontend
-        run: cd frontend && pnpm install
-      - name: test-storybook
-        run: cd frontend && pnpm test:storybook --shard=${{ matrix.shard }}/${{ strategy.job-total }}
   web-settings:
     if: |
       github.event_name == 'merge_group' ||

docs/api/openapi.yml

@@ -3536,11 +3536,6 @@ components:
       - tags
       - spec
       type: object
-    DashboardtypesHeaderOptions:
-      properties:
-        hide:
-          type: boolean
-      type: object
     DashboardtypesHistogramBuckets:
       properties:
         bucketCount:
@@ -3898,7 +3893,6 @@ components:
           signoz/NumberPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesNumberPanelSpec'
           signoz/PieChartPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesPieChartPanelSpec'
           signoz/TablePanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec'
-          signoz/TextPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpec'
           signoz/TimeSeriesPanel: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpec'
         propertyName: kind
       oneOf:
@@ -3909,7 +3903,6 @@ components:
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHistogramPanelSpec'
       - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpec'
-      - $ref: '#/components/schemas/DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpec'
       type: object
     DashboardtypesPanelPluginKind:
       enum:
@@ -3920,7 +3913,6 @@ components:
       - signoz/TablePanel
       - signoz/HistogramPanel
       - signoz/ListPanel
-      - signoz/TextPanel
       type: string
     DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpec:
       properties:
@@ -3994,18 +3986,6 @@ components:
       - kind
       - spec
       type: object
-    DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpec:
-      properties:
-        kind:
-          enum:
-          - signoz/TextPanel
-          type: string
-        spec:
-          $ref: '#/components/schemas/DashboardtypesTextPanelSpec'
-      required:
-      - kind
-      - spec
-      type: object
     DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpec:
       properties:
         kind:
@@ -4297,37 +4277,6 @@ components:
       - color
       - columnName
       type: object
-    DashboardtypesTextAlign:
-      enum:
-      - left
-      - center
-      - right
-      type: string
-    DashboardtypesTextMode:
-      enum:
-      - markdown
-      type: string
-    DashboardtypesTextPanelSpec:
-      properties:
-        headerOptions:
-          $ref: '#/components/schemas/DashboardtypesHeaderOptions'
-        mode:
-          $ref: '#/components/schemas/DashboardtypesTextMode'
-        presentation:
-          $ref: '#/components/schemas/DashboardtypesTextPresentation'
-        text:
-          type: string
-      type: object
-    DashboardtypesTextPresentation:
-      properties:
-        background:
-          nullable: true
-          type: string
-        textAlign:
-          $ref: '#/components/schemas/DashboardtypesTextAlign'
-        verticalAlign:
-          $ref: '#/components/schemas/DashboardtypesVerticalAlign'
-      type: object
     DashboardtypesTextVariableSpec:
       properties:
         constant:
@@ -4537,12 +4486,6 @@ components:
       - kind
       - spec
       type: object
-    DashboardtypesVerticalAlign:
-      enum:
-      - top
-      - center
-      - bottom
-      type: string
     ErrorsJSON:
       properties:
         code:

docs/contributing/go/readme.md

@@ -21,5 +21,4 @@ We **recommend** (almost enforce) reviewing these guides before contributing to
 - [Packages](packages.md) - Naming, layout, and conventions for `pkg/` packages
 - [Service](service.md) - Managed service lifecycle with `factory.Service`
 - [SQL](sql.md) - Database and SQL patterns
-- [SQL Compiler](sqlcompiler.md) - Compiling the list filter DSL to relational-store WHERE clauses
 - [Types](types.md) - Domain types, request/response bodies, and storage rows in `pkg/types/`

docs/contributing/go/sqlcompiler.md

@@ -1,84 +0,0 @@
-# SQL Compiler
-
-List pages (dashboards, alert rules) share one filter DSL in their search bars. [pkg/parser/filterquery/sqlcompiler](/pkg/parser/filterquery/sqlcompiler/compiler.go) compiles a DSL string into a WHERE clause for the relational store: `?`-placeholder SQL plus bind arguments, ready for bun on both SQLite and Postgres. Telemetry filters are a different pipeline. They stay on querybuilder's ClickHouse visitor.
-
-The package owns everything generic about the language. A module adopting it writes exactly one thing: a `FieldResolver` that says which keys exist and what each maps to.
-
-## What is the DSL?
-
-The grammar lives at [grammar/FilterQuery.g4](/grammar/FilterQuery.g4), with the ANTLR-generated parser in [pkg/parser/filterquery/grammar](/pkg/parser/filterquery/grammar). It is the same grammar the telemetry search bars use, so the query language feels identical everywhere. The shapes that matter:
-
-- Boolean structure: parentheses > `NOT` > `AND` > `OR`; adjacent terms with no connective are an implicit `AND`.
-- Comparisons: `key OP value`, e.g. `name CONTAINS cpu`, `created_at > '2025-01-01T00:00:00Z'`, `labels.team IN ('infra', 'platform')`, `labels.env EXISTS`. See the `comparison` rule in the grammar for the full operator list.
-- Free text: a bare or quoted token with no key. Quoting is the escape hatch for a phrase that looks like DSL.
-- Values: bare tokens or quoted strings; `IN` accepts `in(...)` and `[...]` forms.
-
-## What does the framework already cover?
-
-```go
-compiled, errs := sqlcompiler.Compile(query, formatter, resolver)
-```
-
-`Compile` returns either a non-nil `*Compiled` or a list of human-readable errors. An empty query compiles to an empty `Compiled`; callers gate on `IsEmpty()`, not nil. On top of parsing, the package handles:
-
-- Syntax errors, collected with line/column positions instead of failing on the first one.
-- The boolean tree: `AND`/`OR`/`NOT`, parentheses, implicit `AND`, and pruning of empty conditions.
-- Operator extraction, including inversion of `NOT LIKE`, `NOT IN`, `NOT EXISTS` and friends.
-- Predicate builders the resolver calls back into:
-
-| Builder                    | Handles                                                                                                                                                                                                     |
-| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BuildStringOperation`     | `=`, `!=`, `LIKE`/`ILIKE`, `CONTAINS`, `IN` on a string column; escapes `%`/`_` for `CONTAINS`, rejects patterns ending in a dangling backslash, lowers both sides for `ILIKE` so SQLite and Postgres agree |
-| `BuildTimestampComparison` | equality, ranges and `BETWEEN` on RFC3339 timestamps                                                                                                                                                        |
-| `BuildBoolComparison`      | `= true/false`                                                                                                                                                                                              |
-| `BuildFreeTextContains`    | case-insensitive substring match, `COALESCE`d so `NOT (...)` does not drop rows where the column is NULL                                                                                                    |
-
-- Typed value extraction (`ExtractSingleStringValue`, `ExtractStringValueList`, ...) with accumulated errors: the user sees every problem in the query at once.
-- Argument binding through go-sqlbuilder; no value is ever interpolated into the SQL text.
-
-## When do I write a FieldResolver?
-
-Whenever a module adopts the DSL for its list page. The resolver is the per-module policy and the only code you write:
-
-```go
-type FieldResolver interface {
-	ResolveComparison(v *Visitor, key string, operation qbtypesv5.FilterOperator, ctx *grammar.ComparisonContext) string
-	ResolveFreeText(v *Visitor, value string) string
-}
-```
-
-Rules for implementing one:
-
-- Declare the key namespace in `pkg/types/<domain>`: `DSLKey` constants plus a `ReservedOps` map of key to allowed operators. The list API advertises these as `reservedKeywords`, so the frontend suggestions never go stale.
-- Reject a disallowed operator with `v.AddError(...)` and return `""`. Never panic, never fail fast; the compile fails at the end with all errors.
-- Map a key to a column expression through `v.Formatter` (`JSONExtractString`, `LowerExpression`), never by hand, so the expression is valid on both SQLite and Postgres.
-- Delegate the predicate to the `Build*` helpers above; do not hand-build SQL or manage arguments yourself.
-- For a key that lives in a relation table (dashboard tags, rule labels), build an `EXISTS` subquery on a fresh `sqlbuilder.SelectBuilder` and pass that builder into `BuildStringOperation`, so its arguments thread through the compile. For a negative operator, build the positive predicate and toggle `NotExists` on the outer builder.
-
-The reference implementation is the dashboards resolver, [pkg/modules/dashboard/impldashboard/listfilter_resolver.go](/pkg/modules/dashboard/impldashboard/listfilter_resolver.go): reserved keys backed by columns and JSON paths, tag keys via `EXISTS` subqueries, free text across name, description and tags.
-
-## How to wire it in?
-
-Give the module a thin `Compile` wrapper that maps the error list onto the module's error code, as in [pkg/modules/dashboard/impldashboard/listfilter.go](/pkg/modules/dashboard/impldashboard/listfilter.go):
-
-```go
-func Compile(query string, formatter sqlstore.SQLFormatter) (*sqlcompiler.Compiled, error) {
-	compiled, errs := sqlcompiler.Compile(query, formatter, dashboardFieldResolver{})
-	if len(errs) > 0 {
-		return nil, errors.NewInvalidInputf(dashboardtypes.ErrCodeDashboardListFilterInvalid,
-			"invalid filter query: %s", strings.Join(errs, "; "))
-	}
-	return compiled, nil
-}
-```
-
-The store then appends `compiled.SQL` with `compiled.Args` to its list query when `!compiled.IsEmpty()`.
-
-## What should I remember?
-
-- One DSL, one compiler; a new list page adds a `FieldResolver`, not a new parser or SQL layer.
-- Keys and allowed operators live in `pkg/types/<domain>` and are advertised as `reservedKeywords`.
-- Column expressions go through `v.Formatter`; predicates go through the `Build*` helpers.
-- Report problems with `v.AddError` and return `""`; errors accumulate.
-- Relation-table keys use `EXISTS` subqueries on their own builder; negation toggles `NotExists`.
-- This package is for the relational store only; telemetry filtering stays in querybuilder.

frontend/.storybook/preview-head.html

@@ -1,11 +1,9 @@
-<!--
-	`index.html` links Inter from Google Fonts here. The link is parsed before the
-	msw worker has started, so that one request escapes the iframe while every
-	other font request the app makes is answered with an empty stylesheet; the
-	local faces stand in for both.
--->
-<link rel="stylesheet" href="storybook-fonts.css" />
-
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+	href="https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap"
+	rel="stylesheet"
+/>
 <link rel="stylesheet" href="css/uPlot.min.css" />
 
 <script>

frontend/.storybook/public/storybook-fonts.css

@@ -1,50 +0,0 @@
-/*
- * The five families the app pulls from Google Fonts, served from the files in
- * `public/fonts` instead. `msw/appShellHandlers.ts` answers the CDN with an
- * empty stylesheet so no request leaves the iframe, which without this left
- * every story on a fallback for the four families `src/styles.scss` imports at
- * runtime, and on whatever the Inter link in `index.html` happened to fetch
- * before the worker had started.
- */
-
-@font-face {
-	font-family: 'Inter';
-	/* The comma is part of the filename and the dev server serves it raw, so it
-	   stays literal inside the quoted url rather than percent-encoded. */
-	src: url('fonts/Inter-VariableFont_opsz,wght.ttf') format('truetype');
-	font-weight: 100 900;
-	font-style: normal;
-	font-display: swap;
-}
-
-@font-face {
-	font-family: 'Work Sans';
-	src: url('fonts/WorkSans-VariableFont_wght.ttf') format('truetype');
-	font-weight: 100 900;
-	font-style: normal;
-	font-display: swap;
-}
-
-@font-face {
-	font-family: 'Space Mono';
-	src: url('fonts/SpaceMono-Regular.ttf') format('truetype');
-	font-weight: 400;
-	font-style: normal;
-	font-display: swap;
-}
-
-@font-face {
-	font-family: 'Fira Code';
-	src: url('fonts/FiraCode-VariableFont_wght.ttf') format('truetype');
-	font-weight: 300 700;
-	font-style: normal;
-	font-display: swap;
-}
-
-@font-face {
-	font-family: 'Geist Mono';
-	src: url('fonts/GeistMonoVF.woff2') format('woff2');
-	font-weight: 100 900;
-	font-style: normal;
-	font-display: swap;
-}

frontend/.storybook/test-runner.ts

@@ -1,85 +0,0 @@
-import { getStoryContext } from '@storybook/test-runner';
-import type { TestRunnerConfig } from '@storybook/test-runner';
-import type { Page } from 'playwright';
-
-const IGNORED_MESSAGES = [
-	// `preview-head.html` swaps a local stylesheet in for Google Fonts, but the
-	// browser still warns on the real cross-origin one it briefly requests
-	// before msw starts (no CORS headers), regardless of story content.
-	/Can't access cssRules/,
-	// Pre-existing dev-server noise, unrelated to any story.
-	/Couldn't load preload assets/,
-	// Fires because a Jest-driven browser sets a global testing flag React
-	// checks for; unrelated to anything a story does.
-	/current testing environment is not configured to support act/,
-	// React and antd route dev-only warnings (missing keys, DOM nesting, API
-	// deprecations) through `console.error` under this prefix; app-wide and
-	// tracked separately from story regressions.
-	/^Warning: /,
-	// msw's own warning when its response listener count grows across many
-	// story visits in one browser session; not a story defect.
-	/MaxListenersExceededWarning/,
-	// `preview-head.html`'s CSP intentionally blocks third-party iframes
-	// (YouTube embeds, the docs pane) so they hit the real network instead of
-	// an unanswered msw request; the block is the point, not a bug.
-	/violates the following Content Security Policy directive/,
-];
-
-const messagesByPage = new WeakMap<Page, string[]>();
-
-/**
- * Only `console.error` fails a story. `console.warn` is dev-time advice from
- * app code (e.g. `aggregateData is null`) and from the runner itself; an
- * unmocked `/api/` call is a `console.error` in `src/storybook/msw/handlers.ts`.
- */
-const config: TestRunnerConfig = {
-	// msw logs every mocked request at `log`; keep it out of the failure dump
-	// unless the job is re-run with debug logging (GitHub sets RUNNER_DEBUG=1).
-	logLevel: process.env.RUNNER_DEBUG === '1' ? 'info' : 'warn',
-	async preVisit(page): Promise<void> {
-		const existing = messagesByPage.get(page);
-		if (existing) {
-			existing.length = 0;
-			return;
-		}
-
-		const messages: string[] = [];
-		messagesByPage.set(page, messages);
-		page.on('console', (message) => {
-			if (
-				message.type() === 'error' &&
-				!IGNORED_MESSAGES.some((pattern) => pattern.test(message.text()))
-			) {
-				messages.push(`[error] ${message.text()}`);
-			}
-		});
-		// The console message alone ("Failed to load resource") doesn't name the
-		// URL; pairing it with the response is what makes a missing mock
-		// actionable instead of just a status code.
-		page.on('response', (response) => {
-			if (response.status() >= 400) {
-				messages.push(`[response] ${response.status()} ${response.url()}`);
-			}
-		});
-	},
-	async postVisit(page, context): Promise<void> {
-		const messages = messagesByPage.get(page) ?? [];
-		if (messages.length === 0) {
-			return;
-		}
-
-		// A story that deliberately mocks a failure response (e.g. a 500 to test
-		// an error state) logs the error it's testing for; opt it out per-story
-		// with `parameters: { allowConsoleErrors: true }`.
-		const storyContext = await getStoryContext(page, context);
-		if (storyContext.parameters?.allowConsoleErrors) {
-			return;
-		}
-
-		throw new Error(
-			`Story "${context.name}" logged console error/warning:\n${messages.join('\n')}`,
-		);
-	},
-};
-
-export default config;

frontend/__mocks__/uplotMock.ts

@@ -2,6 +2,8 @@
 
 // Mock for uplot library used in tests
 export interface MockUPlotInstance {
+	/** Consumers read `root.parentElement` to detect a re-mounted container. */
+	root: HTMLDivElement;
 	setData: jest.Mock;
 	setSize: jest.Mock;
 	destroy: jest.Mock;
@@ -17,13 +19,20 @@ export interface MockUPlotPaths {
 }
 
 // Create mock instance methods
-const createMockUPlotInstance = (): MockUPlotInstance => ({
-	setData: jest.fn(),
-	setSize: jest.fn(),
-	destroy: jest.fn(),
-	redraw: jest.fn(),
-	setSeries: jest.fn(),
-});
+const createMockUPlotInstance = (target?: HTMLElement): MockUPlotInstance => {
+	const root = document.createElement('div');
+	// Real uPlot mounts its root inside the target; without it a re-render reads
+	// `root.parentElement` off undefined and throws.
+	target?.appendChild(root);
+	return {
+		root,
+		setData: jest.fn(),
+		setSize: jest.fn(),
+		destroy: jest.fn(),
+		redraw: jest.fn(),
+		setSeries: jest.fn(),
+	};
+};
 
 // Path builder: (self, seriesIdx, idx0, idx1) => paths or null
 const createMockPathBuilder = (name: string): jest.Mock =>
@@ -53,14 +62,16 @@ const mockTzDate = jest.fn(
 function MockUPlot(
 	_options: unknown,
 	_data: unknown,
-	_target: HTMLElement,
+	target: HTMLElement,
 ): MockUPlotInstance {
-	return createMockUPlotInstance();
+	return createMockUPlotInstance(target);
 }
 
 // Add static methods to the constructor
 MockUPlot.tzDate = mockTzDate;
 MockUPlot.paths = mockPaths;
+// Pinned so canvas-space maths in draw hooks is deterministic under jsdom.
+MockUPlot.pxRatio = 1;
 
 // Export the constructor as default
 export default MockUPlot;

frontend/package.json

@@ -9,7 +9,6 @@
     "dev": "vite",
     "storybook": "storybook dev -p 6006",
     "storybook:build": "storybook build -o storybook-static",
-    "test:storybook": "bash scripts/test-storybook.sh",
     "build": "vite build",
     "preview": "vite preview",
     "prettify": "oxfmt",
@@ -163,7 +162,6 @@
     "@jest/types": "30.2.0",
     "@storybook/addon-a11y": "10.5.9",
     "@storybook/react-vite": "10.5.9",
-    "@storybook/test-runner": "0.24.5",
     "@testing-library/dom": "8.20.0",
     "@testing-library/jest-dom": "5.16.5",
     "@testing-library/react": "13.4.0",
@@ -235,7 +233,7 @@
   },
   "overrides": {
     "@babel/core@<=7.29.0": ">=7.29.6 <8",
-    "@istanbuljs/load-nyc-config>js-yaml": ">=4.3.1 <5",
+    "@istanbuljs/load-nyc-config>js-yaml": ">=4.2.0 <5",
     "cookie@<0.7.0": ">=0.7.1 <1",
     "dompurify@<=3.4.10": ">=3.4.11 <4",
     "esbuild@>=0.27.3 <0.28.1": ">=0.28.1 <0.29.0",
@@ -244,14 +242,6 @@
     "prismjs@<1.30.0": ">=1.30.0 <2",
     "react-router@>=6.7.0 <6.30.4": ">=6.30.4 <7",
     "tmp@<0.2.6": ">=0.2.6 <0.3.0",
-    "yaml@>=1.0.0 <1.10.3": ">=1.10.3 <2",
-    "brace-expansion@<1.1.18": ">=1.1.18 <2",
-    "brace-expansion@>=2.0.0 <2.1.4": ">=2.1.4 <3",
-    "brace-expansion@>=5.0.0 <5.0.9": ">=5.0.9 <6",
-    "fast-uri@<3.1.5": ">=3.1.5 <4",
-    "immutable@<5.1.8": ">=5.1.8 <6",
-    "js-yaml@>=4.0.0 <4.3.1": ">=4.3.1 <5",
-    "less@<4.5.0": ">=4.5.0 <5",
-    "nanoid@<3.3.18": ">=3.3.18 <4"
+    "yaml@>=1.0.0 <1.10.3": ">=1.10.3 <2"
   }
 }

frontend/scripts/test-storybook.sh

@@ -1,31 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-story_count=$(find src -name '*.stories.tsx' | wc -l)
-if [ "$story_count" -eq 0 ]; then
-	echo "No *.stories.tsx found under src/" >&2
-	exit 1
-fi
-
-# jest splits the sorted story files into contiguous shards and exits 1 when a
-# shard is empty, which happens on every shard above the file count. The runner
-# rejects jest's own `--passWithNoTests`, so skip those shards here.
-for arg in "$@"; do
-	if [[ $arg == --shard=* ]]; then
-		shard_index=${arg#--shard=}
-		if [ "${shard_index%%/*}" -gt "$story_count" ]; then
-			echo "Skipping ${arg#--shard=}: only ${story_count} story files"
-			exit 0
-		fi
-	fi
-done
-
-pnpm storybook --ci --quiet &
-SB_PID=$!
-trap 'kill "$SB_PID" 2>/dev/null || true' EXIT
-
-until curl -sf http://127.0.0.1:6006/index.json >/dev/null 2>&1; do
-	sleep 1
-done
-
-pnpm exec test-storybook --ci --maxWorkers=2 "$@"

frontend/src/api/ErrorResponseHandler.ts

@@ -1,4 +1,4 @@
-import { AxiosError, AxiosResponse, isCancel } from 'axios';
+import { AxiosError, AxiosResponse } from 'axios';
 import { ErrorResponse } from 'types/api';
 import { ErrorStatusCode } from 'types/common';
 
@@ -42,16 +42,6 @@ export function ErrorResponseHandler(error: AxiosError): ErrorResponse {
 		};
 	}
 	if (request) {
-		// Avoid logging error when the request was just cancelled for whatever reason
-		if (isCancel(error)) {
-			return {
-				statusCode: 500,
-				payload: null,
-				error: 'Something went wrong',
-				message: null,
-			};
-		}
-
 		// client never received a response, or request never left
 		console.error('client never received a response, or request never left');
 

frontend/src/api/generated/services/sigNoz.schemas.ts

@@ -5019,57 +5019,6 @@ export interface DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDa
 	spec: DashboardtypesListPanelSpecDTO;
 }
 
-export enum DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpecDTOKind {
-	'signoz/TextPanel' = 'signoz/TextPanel',
-}
-export interface DashboardtypesHeaderOptionsDTO {
-	/**
-	 * @type boolean
-	 */
-	hide?: boolean;
-}
-
-export enum DashboardtypesTextModeDTO {
-	markdown = 'markdown',
-}
-export enum DashboardtypesTextAlignDTO {
-	left = 'left',
-	center = 'center',
-	right = 'right',
-}
-export enum DashboardtypesVerticalAlignDTO {
-	top = 'top',
-	center = 'center',
-	bottom = 'bottom',
-}
-export interface DashboardtypesTextPresentationDTO {
-	/**
-	 * @type string,null
-	 */
-	background?: string | null;
-	textAlign?: DashboardtypesTextAlignDTO;
-	verticalAlign?: DashboardtypesVerticalAlignDTO;
-}
-
-export interface DashboardtypesTextPanelSpecDTO {
-	headerOptions?: DashboardtypesHeaderOptionsDTO;
-	mode?: DashboardtypesTextModeDTO;
-	presentation?: DashboardtypesTextPresentationDTO;
-	/**
-	 * @type string
-	 */
-	text?: string;
-}
-
-export interface DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpecDTO {
-	/**
-	 * @enum signoz/TextPanel
-	 * @type string
-	 */
-	kind: DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpecDTOKind;
-	spec: DashboardtypesTextPanelSpecDTO;
-}
-
 export type DashboardtypesPanelPluginDTO =
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTimeSeriesPanelSpecDTO
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesBarChartPanelSpecDTO
@@ -5077,8 +5026,7 @@ export type DashboardtypesPanelPluginDTO =
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesPieChartPanelSpecDTO
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTablePanelSpecDTO
 	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesHistogramPanelSpecDTO
-	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpecDTO
-	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesTextPanelSpecDTO;
+	| DashboardtypesPanelPluginVariantGithubComSigNozSignozPkgTypesDashboardtypesListPanelSpecDTO;
 
 export enum Querybuildertypesv5RequestTypeDTO {
 	scalar = 'scalar',
@@ -6002,7 +5950,6 @@ export enum DashboardtypesPanelPluginKindDTO {
 	'signoz/TablePanel' = 'signoz/TablePanel',
 	'signoz/HistogramPanel' = 'signoz/HistogramPanel',
 	'signoz/ListPanel' = 'signoz/ListPanel',
-	'signoz/TextPanel' = 'signoz/TextPanel',
 }
 /**
  * @nullable

frontend/src/constants/panelTypes.ts

@@ -31,8 +31,6 @@ export const getComponentForPanelType = (
 		[PANEL_TYPES.BAR]: Uplot,
 		[PANEL_TYPES.PIE]: null,
 		[PANEL_TYPES.HISTOGRAM]: Uplot,
-		// Dashboards v2 renders this kind; nothing reaches the V1 chart map for it.
-		[PANEL_TYPES.TEXT]: null,
 		[PANEL_TYPES.EMPTY_WIDGET]: null,
 	};
 

frontend/src/constants/queryBuilder.ts

@@ -376,7 +376,6 @@ export enum PANEL_TYPES {
 	BAR = 'bar',
 	PIE = 'pie',
 	HISTOGRAM = 'histogram',
-	TEXT = 'text',
 	EMPTY_WIDGET = 'EMPTY_WIDGET',
 }
 

frontend/src/container/BillingContainer/BillingContainer.tsx

@@ -376,9 +376,7 @@ export default function BillingContainer(): JSX.Element {
 				</Typography.Link>
 			</AuthZTooltip>
 			{` if your payment information has changed. Email us at `}
-			<Typography.Text as="span" color="muted">
-				cloud-support@signoz.io
-			</Typography.Text>
+			<Typography.Text color="muted">cloud-support@signoz.io</Typography.Text>
 			{` otherwise. Be sure to provide this information immediately to avoid interruption to your service.`}
 		</Typography>
 	);

frontend/src/container/Home/Services/ServiceTraces.tsx

@@ -174,7 +174,6 @@ export default function ServiceTraces({
 						columns={columns}
 						dataSource={top5Services}
 						pagination={false}
-						rowKey="serviceName"
 						className="services-table"
 						onRow={(record: ServicesList): Record<string, unknown> => ({
 							onClick: (event: React.MouseEvent): void => {

frontend/src/container/InfraMonitoringK8sV2/Base/K8sOptionsSidePanel.tsx

@@ -216,7 +216,7 @@ function K8sOptionsSidePanel<TData>({
 					);
 					return (
 						<div className={styles.columnItem} key={column.id}>
-							<Typography.Text as="span" size="sm" className={styles.columnLabel}>
+							<Typography.Text size="sm" className={styles.columnLabel}>
 								{column.label}
 							</Typography.Text>
 							{column.canBeHidden ? (

frontend/src/container/WidgetCard/Card/FullView/contants.ts

@@ -29,6 +29,5 @@ export const PANEL_TYPES_VS_FULL_VIEW_TABLE: PanelTypeAndGraphManagerVisibilityP
 		BAR: true,
 		PIE: false,
 		HISTOGRAM: false,
-		TEXT: false,
 		EMPTY_WIDGET: false,
 	};

frontend/src/container/WidgetCard/Panels/constants.ts

@@ -14,8 +14,6 @@ export const PanelTypeVsPanelWrapper = {
 	[PANEL_TYPES.LIST]: ListPanelWrapper,
 	[PANEL_TYPES.VALUE]: ValuePanelWrapper,
 	[PANEL_TYPES.TRACE]: null,
-	// Dashboards v2 renders this kind; the V1 wrapper map is never asked for it.
-	[PANEL_TYPES.TEXT]: null,
 	[PANEL_TYPES.EMPTY_WIDGET]: null,
 	[PANEL_TYPES.PIE]: PiePanelWrapper,
 	[PANEL_TYPES.BAR]: BarPanel,

frontend/src/lib/uPlotV2/components/ColorBar/ColorBar.module.scss

@@ -0,0 +1,75 @@
+.container {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	width: 100%;
+	padding: 4px 12px 8px;
+	box-sizing: border-box;
+}
+
+.label {
+	flex: 0 0 auto;
+	font-size: 11px;
+	line-height: 16px;
+	color: var(--text-vanilla-400);
+	font-variant-numeric: tabular-nums;
+}
+
+.track {
+	position: relative;
+	flex: 1 1 auto;
+	height: 8px;
+	border-radius: 2px;
+	border: 1px solid var(--l2-border);
+}
+
+.marker {
+	position: absolute;
+	top: -3px;
+	bottom: -3px;
+	width: 2px;
+	transform: translateX(-1px);
+	background: var(--text-vanilla-100);
+	border-radius: 1px;
+}
+
+.caption {
+	flex: 0 0 auto;
+	font-size: 10px;
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	color: var(--text-vanilla-400);
+}
+
+.keys {
+	display: flex;
+	flex: 0 0 auto;
+	gap: 12px;
+	align-items: center;
+}
+
+.key {
+	display: flex;
+	gap: 5px;
+	align-items: center;
+	font-size: 11px;
+	color: var(--text-vanilla-400);
+}
+
+.swatch,
+.hatchSwatch {
+	width: 11px;
+	height: 11px;
+	border-radius: 2px;
+	border: 1px solid var(--l2-border);
+	box-sizing: border-box;
+}
+
+// Approximates the canvas hatch painted over null cells.
+.hatchSwatch {
+	background-image: repeating-linear-gradient(
+		45deg,
+		transparent 0 2px,
+		var(--text-vanilla-400) 2px 3px
+	);
+}

frontend/src/lib/uPlotV2/components/ColorBar/ColorBar.tsx

@@ -0,0 +1,81 @@
+import { useMemo } from 'react';
+
+import Styles from './ColorBar.module.scss';
+
+export interface ColorBarProps {
+	/** Low to high, drawn as hard-edged segments so the bar shows the same set of
+	 *  colours as the cells. */
+	ramp: string[];
+	minLabel: string;
+	maxLabel: string;
+	/** 0..1. `null` hides the marker. */
+	markerPosition?: number | null;
+	/** What the colour encodes, e.g. "count". */
+	label?: string;
+	/** Keys for the two states a ramp cannot express: a hatched data gap, and a
+	 *  genuine zero at the bottom. Without them the difference is guesswork. */
+	showStateKeys?: boolean;
+	'data-testid'?: string;
+}
+
+/** What a colour means, plus a marker for the value under the cursor. */
+export default function ColorBar({
+	ramp,
+	minLabel,
+	maxLabel,
+	markerPosition = null,
+	label,
+	showStateKeys = true,
+	'data-testid': testId = 'color-bar',
+}: ColorBarProps): JSX.Element | null {
+	const gradient = useMemo(() => {
+		if (ramp.length === 0) {
+			return undefined;
+		}
+		if (ramp.length === 1) {
+			return ramp[0];
+		}
+		const stops = ramp.flatMap((color, index) => {
+			const from = (index / ramp.length) * 100;
+			const to = ((index + 1) / ramp.length) * 100;
+			return [`${color} ${from}%`, `${color} ${to}%`];
+		});
+		return `linear-gradient(to right, ${stops.join(', ')})`;
+	}, [ramp]);
+
+	if (gradient === undefined) {
+		return null;
+	}
+
+	const clampedMarker =
+		markerPosition === null ? null : Math.min(Math.max(markerPosition, 0), 1);
+
+	return (
+		<div className={Styles.container} data-testid={testId}>
+			{label && <span className={Styles.caption}>{label}</span>}
+			<span className={Styles.label}>{minLabel}</span>
+			<div className={Styles.track} style={{ background: gradient }}>
+				{clampedMarker !== null && (
+					<span
+						className={Styles.marker}
+						style={{ left: `${clampedMarker * 100}%` }}
+						data-testid={`${testId}-marker`}
+					/>
+				)}
+			</div>
+			<span className={Styles.label}>{maxLabel}</span>
+			{showStateKeys && (
+				<div className={Styles.keys} data-testid={`${testId}-state-keys`}>
+					<span className={Styles.key}>
+						<span className={Styles.hatchSwatch} />
+						no data
+					</span>
+					<span className={Styles.key}>
+						<span className={Styles.swatch} style={{ background: ramp[0] }} />
+						count 0
+					</span>
+				</div>
+			)}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/ColorBar/__tests__/ColorBar.test.tsx

@@ -0,0 +1,94 @@
+import { render, screen } from '@testing-library/react';
+
+import ColorBar from '../ColorBar';
+
+const RAMP = ['#111111', '#555555', '#999999', '#dddddd'];
+
+describe('ColorBar', () => {
+	it('renders the domain labels', () => {
+		render(<ColorBar ramp={RAMP} minLabel="0" maxLabel="1,204" />);
+
+		expect(screen.getByText('0')).toBeInTheDocument();
+		expect(screen.getByText('1,204')).toBeInTheDocument();
+	});
+
+	it('renders nothing without a ramp', () => {
+		const { container } = render(
+			<ColorBar ramp={[]} minLabel="0" maxLabel="0" />,
+		);
+
+		expect(container).toBeEmptyDOMElement();
+	});
+
+	it('hides the marker when nothing is hovered', () => {
+		render(<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" />);
+
+		expect(screen.queryByTestId('color-bar-marker')).not.toBeInTheDocument();
+	});
+
+	it('positions the marker at the hovered value', () => {
+		render(
+			<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" markerPosition={0.25} />,
+		);
+
+		expect(screen.getByTestId('color-bar-marker')).toHaveStyle({ left: '25%' });
+	});
+
+	it('clamps a marker outside the ramp to its ends', () => {
+		const { rerender } = render(
+			<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" markerPosition={-2} />,
+		);
+		expect(screen.getByTestId('color-bar-marker')).toHaveStyle({ left: '0%' });
+
+		rerender(
+			<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" markerPosition={4} />,
+		);
+		expect(screen.getByTestId('color-bar-marker')).toHaveStyle({ left: '100%' });
+	});
+
+	it('keys the two states a colour ramp cannot express', () => {
+		render(<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" />);
+
+		expect(screen.getByText('no data')).toBeInTheDocument();
+		expect(screen.getByText('count 0')).toBeInTheDocument();
+	});
+
+	it('draws the count-0 key with the bottom of the ramp', () => {
+		render(<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" />);
+
+		expect(screen.getByText('count 0').firstChild).toHaveStyle({
+			background: RAMP[0],
+		});
+	});
+
+	it('hides the state keys when asked', () => {
+		render(
+			<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" showStateKeys={false} />,
+		);
+
+		expect(screen.queryByText('no data')).not.toBeInTheDocument();
+	});
+
+	it('captions what the colour encodes', () => {
+		render(<ColorBar ramp={RAMP} minLabel="0" maxLabel="10" label="count" />);
+
+		expect(screen.getByText('count')).toBeInTheDocument();
+	});
+
+	it('renders hard-edged segments so the bar matches the drawn cells', () => {
+		render(
+			<ColorBar
+				ramp={['#111111', '#dddddd']}
+				minLabel="0"
+				maxLabel="10"
+				data-testid="scale"
+			/>,
+		);
+
+		const track = screen.getByTestId('scale').querySelector('div');
+		expect(track).toHaveStyle({
+			background:
+				'linear-gradient(to right, #111111 0%, #111111 50%, #dddddd 50%, #dddddd 100%)',
+		});
+	});
+});

frontend/src/lib/uPlotV2/components/Legend/Legend.module.scss

@@ -1,57 +0,0 @@
-@use '../../../../styles/scrollbar' as *;
-
-.container {
-	position: relative;
-	display: flex;
-	flex-direction: column;
-	height: 100%;
-	width: 100%;
-	// Let the flex children shrink below their content height so the series list
-	// scrolls within the capped legend height instead of overflowing the wrapper
-	// (the default min-height:auto would block the shrink).
-	min-height: 0;
-}
-
-.scroller {
-	// flex:1 + min-height:0 pins the scroller to the space left after the
-	// toolbar instead of growing to fit every row.
-	flex: 1;
-	min-height: 0;
-	height: 100%;
-	width: 100%;
-	padding-right: var(--spacing-2);
-	overflow-x: hidden;
-	overscroll-behavior: contain;
-
-	@include custom-scrollbar;
-}
-
-.gridItem {
-	// Or the item keeps its content width and the label never ellipsizes.
-	min-width: 0;
-	max-width: 100%;
-}
-
-.gridList {
-	min-width: 0;
-	display: grid;
-	grid-auto-flow: row;
-	// min() keeps the column inside a narrow panel, where a wider one would push
-	// the row's actions out of the clipped area.
-	grid-template-columns: repeat(
-		auto-fill,
-		minmax(min(var(--legend-item-width, 240px), 100%), 1fr)
-	);
-	gap: var(--spacing-1) var(--spacing-4);
-}
-
-.container.isRight .gridList {
-	grid-template-columns: 1fr;
-}
-
-.emptyState {
-	padding: var(--spacing-16) 0;
-	font-size: var(--font-size-xs);
-	color: var(--l3-foreground);
-	text-align: center;
-}

frontend/src/lib/uPlotV2/components/Legend/Legend.styles.scss

@@ -0,0 +1,204 @@
+@use '../../../../styles/scrollbar' as *;
+
+.legend-search-container {
+	flex-shrink: 0;
+	width: 100%;
+	padding-right: 8px;
+
+	.legend-search-input {
+		font-size: 12px;
+	}
+}
+
+.legend-container {
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+	gap: 12px;
+	height: 100%;
+	width: 100%;
+	// Allow the flex children to shrink below their content height so the
+	// virtualized grid scrolls within the capped legend height instead of
+	// overflowing the wrapper (default min-height:auto would block the shrink).
+	min-height: 0;
+
+	&:has(.legend-item-focused) .legend-item {
+		opacity: 0.3;
+	}
+
+	&:has(.legend-item-focused) .legend-item.legend-item-focused {
+		opacity: 1;
+	}
+
+	.legend-empty-state {
+		font-size: 12px;
+		color: var(--l2-foreground);
+		text-align: center;
+		padding: 12px;
+		padding: 2rem 0;
+	}
+
+	.legend-virtuoso-container {
+		// flex:1 + min-height:0 pins the scroller to the space left after the
+		// search box (RIGHT legend) and lets it scroll instead of growing to fit
+		// every row — without this the grid overflows a BOTTOM legend's fixed height.
+		flex: 1;
+		min-height: 0;
+		height: 100%;
+		width: 100%;
+
+		.virtuoso-grid-list {
+			min-width: 0;
+			display: grid;
+			grid-auto-flow: row;
+			grid-template-columns: repeat(
+				auto-fill,
+				minmax(var(--legend-average-width, 240px), 1fr)
+			);
+			column-gap: 12px;
+		}
+
+		.virtuoso-grid-item {
+			min-width: 0;
+		}
+
+		&.legend-virtuoso-container-right {
+			.virtuoso-grid-list {
+				grid-template-columns: 1fr;
+			}
+		}
+
+		&.legend-virtuoso-container-single-row {
+			.virtuoso-grid-list {
+				grid-template-columns: repeat(
+					auto-fit,
+					minmax(var(--legend-average-width, 240px), max-content)
+				);
+				justify-content: center;
+			}
+		}
+
+		@include custom-scrollbar;
+	}
+}
+
+.legend-row {
+	padding: 4px 0;
+	display: flex;
+	align-items: center;
+	flex-wrap: wrap;
+	gap: 8px 16px;
+
+	&.legend-single-row {
+		justify-content: center;
+	}
+
+	&.legend-row-right {
+		flex-direction: column;
+		align-items: flex-start;
+		justify-content: flex-start;
+	}
+	&.legend-row-bottom {
+		flex-direction: row;
+	}
+}
+
+.legend-item {
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	padding: 4px 8px;
+	// Include padding within the width so a full-width row (legend-item-right) fits its
+	// column instead of overflowing by the 16px horizontal padding — there is no global
+	// border-box reset, so the default content-box would make it overflow.
+	box-sizing: border-box;
+	max-width: 100%;
+	overflow: hidden;
+	border-radius: 4px;
+	cursor: pointer;
+
+	&.legend-item-right {
+		width: 100%;
+	}
+
+	&.legend-item-off {
+		opacity: 0.3;
+		text-decoration: line-through;
+		text-decoration-thickness: 1px;
+	}
+
+	&.legend-item-focused {
+		opacity: 1;
+	}
+
+	.legend-item-label-trigger {
+		display: flex;
+		align-items: center;
+		gap: 6px;
+		flex: 1;
+		min-width: 0;
+		cursor: pointer;
+	}
+
+	.legend-marker {
+		border-width: 2px;
+		border-style: solid;
+		border-radius: 50%;
+		min-width: 11px;
+		min-height: 11px;
+		width: 11px;
+		height: 11px;
+		flex-shrink: 0;
+		cursor: pointer;
+		transition: transform 0.2s ease;
+		position: relative;
+
+		&:hover {
+			transform: scale(1.2);
+			box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.3);
+		}
+
+		&:active {
+			transform: scale(0.9);
+		}
+	}
+
+	.legend-label {
+		flex: 1;
+		font-size: 12px;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+		min-width: 0;
+		user-select: none;
+	}
+
+	.legend-copy-button {
+		// Always laid out (space reserved) but transparent, so revealing it on
+		// hover fades the icon in without reflowing the row / shifting the label.
+		// Shrink the shared icon Button (defaults to a 2rem square) to the
+		// compact legend row via its size tokens.
+		--button-height: auto;
+		--button-width: auto;
+		--button-padding: 2px;
+
+		opacity: 0;
+		flex-shrink: 0;
+		color: var(--l2-foreground);
+		border-radius: 4px;
+		transition:
+			opacity 0.15s ease,
+			color 0.15s ease;
+
+		&:hover {
+			color: var(--l1-foreground);
+		}
+	}
+
+	&:hover {
+		background: var(--l3-background);
+		.legend-copy-button {
+			opacity: 1;
+		}
+	}
+}

frontend/src/lib/uPlotV2/components/Legend/Legend.tsx

@@ -1,106 +1,139 @@
 import { useCallback, useMemo, useRef, useState } from 'react';
 import { VirtuosoGrid } from 'react-virtuoso';
+import { Input } from 'antd';
+import { TooltipSimple } from '@signozhq/ui/tooltip';
 import cx from 'classnames';
+import { useResizeObserver } from 'hooks/useDimensions';
 import { LegendItem } from 'lib/uPlotV2/config/types';
+import CopyButton from 'periscope/components/CopyButton/CopyButton';
 
-import { LegendAction, LegendPosition, LegendProps } from '../types';
+import { LegendPosition, LegendProps } from '../types';
 
-import { LEGEND_ITEM_EXTRA_WIDTH, MAX_LEGEND_WIDTH } from './constants';
-import LegendRow from './LegendRow';
-import LegendToolbar from './LegendToolbar';
-import { filterLegendItems, getShownSeriesState } from './utils';
+import './Legend.styles.scss';
 
-import styles from './Legend.module.scss';
+export const MAX_LEGEND_WIDTH = 240;
 
 /**
- * Presentational legend, source-agnostic: the uPlot charts feed it via
- * UPlotLegend, Pie feeds it directly. Every state change is delegated.
+ * Presentational legend. Renders the supplied `items` (markers + labels, an
+ * optional copy button, and a search box for the RIGHT position) and delegates
+ * all interaction to the container handlers. Source-agnostic — the uPlot
+ * charts feed it via UPlotLegend; Pie feeds it directly.
  */
 export default function Legend({
 	items,
 	position,
 	averageLegendWidth = MAX_LEGEND_WIDTH,
 	focusedSeriesIndex,
-	onAction,
+	onClick,
+	onMouseMove,
+	onMouseLeave,
 	showCopy = true,
 }: LegendProps): JSX.Element {
 	const legendContainerRef = useRef<HTMLDivElement | null>(null);
-	const [filterQuery, setFilterQuery] = useState('');
+	const [legendSearchQuery, setLegendSearchQuery] = useState('');
 
-	const itemWidth = averageLegendWidth + LEGEND_ITEM_EXTRA_WIDTH;
-	const isRightPosition = position === LegendPosition.RIGHT;
+	// Search is intrinsic to the right-positioned legend.
+	const searchEnabled = position === LegendPosition.RIGHT;
+	const { width: containerWidth } = useResizeObserver(legendContainerRef);
 
-	const { visibleCount, soleShownSeriesIndex } = useMemo(
-		() => getShownSeriesState(items),
-		[items],
-	);
+	const isSingleRow = useMemo(() => {
+		if (position !== LegendPosition.BOTTOM || containerWidth <= 0) {
+			return false;
+		}
+		const totalLegendWidth = items.length * (averageLegendWidth + 16);
+		const totalRows = Math.ceil(totalLegendWidth / containerWidth);
+		return totalRows <= 1;
+	}, [averageLegendWidth, items.length, position, containerWidth]);
 
-	// A bottom legend gets two rows; spending one on chrome costs more chart than
-	// the readout is worth.
-	const showToolbar = isRightPosition && items.length > 0;
-	const showFilter = showToolbar;
+	const visibleLegendItems = useMemo(() => {
+		if (!searchEnabled || !legendSearchQuery.trim()) {
+			return items;
+		}
 
-	const effectiveQuery = showFilter ? filterQuery : '';
-
-	const visibleLegendItems = useMemo(
-		() => filterLegendItems(items, effectiveQuery),
-		[items, effectiveQuery],
-	);
-
-	const isEmptyState =
-		!!effectiveQuery.trim() && visibleLegendItems.length === 0;
-
-	const isAllShown = visibleCount === items.length;
-
-	// A row that unmounts under the pointer never fires its own mouseleave.
-	const handleMouseLeave = useCallback(
-		(): void => onAction({ type: LegendAction.HOVER, seriesIndex: null }),
-		[onAction],
-	);
+		const query = legendSearchQuery.trim().toLowerCase();
+		return items.filter((item) => item.label?.toLowerCase().includes(query));
+	}, [searchEnabled, legendSearchQuery, items]);
 
 	const renderLegendItem = useCallback(
-		(item: LegendItem): JSX.Element => (
-			<LegendRow
-				key={item.seriesIndex}
-				item={item}
-				isSoleShown={soleShownSeriesIndex === item.seriesIndex}
-				isAllShown={isAllShown}
-				isFocused={focusedSeriesIndex === item.seriesIndex}
-				showCopy={showCopy}
-				onAction={onAction}
-			/>
-		),
-		[soleShownSeriesIndex, isAllShown, focusedSeriesIndex, showCopy, onAction],
+		(item: LegendItem): JSX.Element => {
+			// `color` is uPlot's stroke union (string | fn | gradient); only a string
+			// is a usable CSS colour for the marker.
+			const markerColor = typeof item.color === 'string' ? item.color : undefined;
+			return (
+				<div
+					key={item.seriesIndex}
+					data-legend-item-id={item.seriesIndex}
+					className={cx('legend-item', `legend-item-${position.toLowerCase()}`, {
+						'legend-item-off': !item.show,
+						'legend-item-focused': focusedSeriesIndex === item.seriesIndex,
+					})}
+				>
+					<TooltipSimple title={item.label} arrow side="top" disableHoverableContent>
+						<div className="legend-item-label-trigger">
+							<div
+								className="legend-marker"
+								style={{ borderColor: markerColor }}
+								data-is-legend-marker={true}
+							/>
+							<span className="legend-label">{item.label}</span>
+						</div>
+					</TooltipSimple>
+					{showCopy && (
+						<CopyButton
+							value={item.label ?? ''}
+							size={12}
+							className="legend-copy-button"
+							ariaLabel={`Copy ${item.label}`}
+							testId="legend-copy"
+						/>
+					)}
+				</div>
+			);
+		},
+		[focusedSeriesIndex, position, showCopy],
 	);
 
+	const isEmptyState = useMemo(() => {
+		if (!searchEnabled || !legendSearchQuery.trim()) {
+			return false;
+		}
+		return visibleLegendItems.length === 0;
+	}, [searchEnabled, legendSearchQuery, visibleLegendItems]);
+
 	return (
 		<div
 			ref={legendContainerRef}
-			className={cx(styles.container, {
-				[styles.isRight]: isRightPosition,
-			})}
-			style={{ ['--legend-item-width' as string]: `${itemWidth}px` }}
-			onMouseLeave={handleMouseLeave}
-			data-testid="legend-container"
+			className="legend-container"
+			onClick={onClick}
+			onMouseMove={onMouseMove}
+			onMouseLeave={onMouseLeave}
+			style={{
+				['--legend-average-width' as string]: `${averageLegendWidth + 16}px`, // 16px is the marker width
+			}}
 		>
-			{showToolbar && (
-				<LegendToolbar
-					visibleCount={visibleCount}
-					totalCount={items.length}
-					showFilter={showFilter}
-					filterQuery={filterQuery}
-					onFilterQueryChange={setFilterQuery}
-				/>
+			{searchEnabled && (
+				<div className="legend-search-container">
+					<Input
+						allowClear
+						placeholder="Search..."
+						value={legendSearchQuery}
+						onChange={(e): void => setLegendSearchQuery(e.target.value)}
+						data-testid="legend-search-input"
+						className="legend-search-input"
+					/>
+				</div>
 			)}
 			{isEmptyState ? (
-				<div className={styles.emptyState}>
-					No series found matching &quot;{effectiveQuery}&quot;
+				<div className="legend-empty-state">
+					No series found matching &quot;{legendSearchQuery}&quot;
 				</div>
 			) : (
 				<VirtuosoGrid
-					className={styles.scroller}
-					listClassName={styles.gridList}
-					itemClassName={styles.gridItem}
+					className={cx(
+						'legend-virtuoso-container',
+						`legend-virtuoso-container-${position.toLowerCase()}`,
+						{ 'legend-virtuoso-container-single-row': isSingleRow },
+					)}
 					data={visibleLegendItems}
 					itemContent={(_, item): JSX.Element => renderLegendItem(item)}
 				/>

frontend/src/lib/uPlotV2/components/Legend/LegendRow.module.scss

@@ -1,170 +0,0 @@
-.row {
-	// Width of the revealed actions, given up by the label on hover only.
-	--legend-actions-reserve: 78px;
-
-	position: relative;
-	display: flex;
-	align-items: center;
-	gap: var(--spacing-4);
-	height: 28px;
-	padding: 0 var(--spacing-3) 0 var(--spacing-4);
-	box-sizing: border-box;
-	width: 100%;
-	max-width: 100%;
-	min-width: 0;
-	border-radius: var(--radius);
-	cursor: pointer;
-	transition: background 160ms linear;
-
-	&:hover,
-	&:focus-visible {
-		background: var(--l3-background);
-	}
-}
-
-.isFocused {
-	background: var(--l3-background);
-}
-
-.marker {
-	// Reads as a checkbox without being one: filled when shown, hollow when
-	// hidden, deliberately not a check glyph.
-	flex: 0 0 auto;
-	box-sizing: border-box;
-	position: relative;
-	// Above the actions, so a narrow row's chip never covers the series colour.
-	z-index: 4;
-	width: 12px;
-	height: 12px;
-	padding: 0;
-	appearance: none;
-	border-width: 1.5px;
-	border-style: solid;
-	border-radius: var(--radius);
-	cursor: pointer;
-	transition:
-		transform 200ms ease,
-		box-shadow 200ms ease,
-		background-color 160ms linear,
-		opacity 160ms linear;
-
-	&:hover {
-		transform: scale(1.2);
-		box-shadow: 0 0 0 2px
-			color-mix(in srgb, var(--l1-foreground) 30%, transparent);
-	}
-
-	&:active {
-		transform: scale(0.9);
-	}
-
-	&:disabled {
-		cursor: default;
-	}
-
-	&:disabled:hover {
-		transform: none;
-		box-shadow: none;
-	}
-}
-
-// Series names run long and have no spaces to break on, so they need both a
-// cap and a break rule or the tooltip becomes one panel-wide line.
-.rowTooltip {
-	max-width: 420px;
-	white-space: normal;
-	overflow-wrap: anywhere;
-}
-
-.label {
-	flex: 1 1 auto;
-	box-sizing: border-box;
-	width: 100%;
-	min-width: 0;
-	overflow: hidden;
-	text-overflow: ellipsis;
-	white-space: nowrap;
-	font-family: var(--font-mono);
-	font-size: var(--font-size-xs);
-	letter-spacing: -0.01em;
-	color: var(--l2-foreground);
-	user-select: none;
-}
-
-.isHidden .marker {
-	opacity: 0.45;
-}
-
-.isHidden .label {
-	color: var(--l3-foreground);
-	text-decoration: line-through;
-	text-decoration-thickness: 1px;
-}
-
-/* Row actions */
-
-.actions {
-	position: absolute;
-	top: var(--spacing-2);
-	right: var(--spacing-3);
-	z-index: 3;
-	display: flex;
-	align-items: center;
-	gap: var(--spacing-2);
-	padding-left: var(--spacing-5, 10px);
-	// Sits on the row's hover background and masks the label's tail behind it.
-	background: var(--l3-background);
-	box-shadow: -8px 0 8px var(--l3-background);
-	opacity: 0;
-	transform: translateX(10px);
-	pointer-events: none;
-	transition:
-		opacity 180ms cubic-bezier(0.08, 0.52, 0.52, 1),
-		transform 180ms cubic-bezier(0.08, 0.52, 0.52, 1);
-}
-
-// :focus-visible, not :focus-within — the latter also matches the click that
-// just toggled the series, leaving the actions stuck open.
-.row:hover .actions,
-.row:focus-visible .actions,
-.row:has(:focus-visible) .actions {
-	opacity: 1;
-	transform: translateX(0);
-	pointer-events: auto;
-}
-
-// The cap spares rows sized to their actions, not their label.
-.row:hover .label,
-.row:focus-visible .label,
-.row:has(:focus-visible) .label {
-	padding-right: min(var(--legend-actions-reserve), 50%);
-}
-
-.actionTrigger {
-	display: inline-flex;
-}
-
-.actionButton {
-	--button-height: 20px;
-	--button-width: 20px;
-	--button-padding: 0;
-	--button-variant-ghost-color: var(--l3-foreground);
-	--button-variant-ghost-hover-color: var(--l1-foreground);
-
-	flex-shrink: 0;
-}
-
-.actionButton.scopeButton {
-	--button-width: auto;
-	--button-padding: 0 var(--spacing-4);
-	--button-font-size: var(--font-size-xs);
-	--button-border-radius: calc(var(--radius) * 4);
-	--button-base-border-width: 1px;
-	// --l2-border is the actions bar's own background: one step up reads.
-	--button-base-border-color: var(--l3-border);
-
-	border-style: solid;
-}
-.actionButton.scopeButton:hover {
-	border-color: var(--l2-border);
-}

frontend/src/lib/uPlotV2/components/Legend/LegendRow.tsx

@@ -1,182 +0,0 @@
-import { KeyboardEvent, memo, MouseEvent, useCallback } from 'react';
-import { Button } from '@signozhq/ui/button';
-import { TooltipSimple } from '@signozhq/ui/tooltip';
-import cx from 'classnames';
-import { LegendItem } from 'lib/uPlotV2/config/types';
-import CopyButton from 'periscope/components/CopyButton/CopyButton';
-
-import { LegendAction, OnLegendAction } from '../types';
-
-import { LEGEND_TOOLTIP_DELAY_MS } from './constants';
-import styles from './LegendRow.module.scss';
-
-export interface LegendRowProps {
-	item: LegendItem;
-	/** The only series currently shown, so hiding it is refused. */
-	isSoleShown: boolean;
-	/** Nothing is hidden, so the row's action can only narrow the selection. */
-	isAllShown: boolean;
-	isFocused: boolean;
-	showCopy: boolean;
-	onAction: OnLegendAction;
-}
-
-/**
- * One legend row. The marker is its own target for excluding a single series —
- * the one thing the row click can't do while everything is showing. The actions
- * overlay the label's tail rather than taking layout width, and their reveal is
- * pure CSS.
- */
-function LegendRow({
-	item,
-	isSoleShown,
-	isAllShown,
-	isFocused,
-	showCopy,
-	onAction,
-}: LegendRowProps): JSX.Element {
-	const { seriesIndex, show } = item;
-	const label = item.label ?? '';
-	const isShowAllAction = show && !isAllShown;
-	const scopeActionLabel = isShowAllAction
-		? 'Show all series'
-		: 'Show only current series';
-	// `color` is uPlot's stroke union (string | fn | gradient); only a string is
-	// a usable CSS colour for the marker.
-	const seriesColor = typeof item.color === 'string' ? item.color : undefined;
-
-	/** Everything showing -> isolate; showing alone -> restore all. */
-	const handleRowClick = useCallback((): void => {
-		if (isSoleShown) {
-			onAction({ type: LegendAction.SHOW_ALL });
-			return;
-		}
-		onAction({
-			type: isAllShown ? LegendAction.SHOW_ONLY : LegendAction.TOGGLE,
-			seriesIndex,
-		});
-	}, [isSoleShown, isAllShown, onAction, seriesIndex]);
-
-	const handleMarkerClick = useCallback(
-		(event: MouseEvent<HTMLButtonElement>): void => {
-			event.stopPropagation();
-			onAction({ type: LegendAction.TOGGLE, seriesIndex });
-		},
-		[onAction, seriesIndex],
-	);
-
-	const handleKeyDown = useCallback(
-		(event: KeyboardEvent<HTMLDivElement>): void => {
-			// Let the row actions handle their own keys.
-			if (event.target !== event.currentTarget) {
-				return;
-			}
-			if (event.key === 'Enter' || event.key === ' ') {
-				event.preventDefault();
-				handleRowClick();
-			}
-		},
-		[handleRowClick],
-	);
-
-	const handleScopeClick = useCallback(
-		(event: MouseEvent<HTMLButtonElement>): void => {
-			event.stopPropagation();
-			if (isShowAllAction) {
-				onAction({ type: LegendAction.SHOW_ALL });
-				return;
-			}
-			onAction({ type: LegendAction.SHOW_ONLY, seriesIndex });
-		},
-		[isShowAllAction, onAction, seriesIndex],
-	);
-
-	const handleMouseEnter = useCallback(
-		(): void => onAction({ type: LegendAction.HOVER, seriesIndex }),
-		[onAction, seriesIndex],
-	);
-
-	const handleMouseLeave = useCallback(
-		(): void => onAction({ type: LegendAction.HOVER, seriesIndex: null }),
-		[onAction],
-	);
-
-	return (
-		<div
-			className={cx(styles.row, {
-				[styles.isHidden]: !show,
-				[styles.isFocused]: isFocused,
-			})}
-			data-legend-item-id={seriesIndex}
-			data-testid={`legend-item-${seriesIndex}`}
-			role="switch"
-			tabIndex={0}
-			aria-checked={show}
-			aria-label={label}
-			onClick={handleRowClick}
-			onKeyDown={handleKeyDown}
-			onMouseEnter={handleMouseEnter}
-			onMouseLeave={handleMouseLeave}
-		>
-			<button
-				type="button"
-				className={styles.marker}
-				style={{
-					borderColor: seriesColor,
-					backgroundColor: show ? seriesColor : 'transparent',
-				}}
-				onClick={handleMarkerClick}
-				disabled={isSoleShown}
-				aria-label={`${show ? 'Hide' : 'Show'} ${label}`}
-				data-is-legend-marker={true}
-				data-testid={`legend-marker-${seriesIndex}`}
-			/>
-			<TooltipSimple
-				title={label}
-				arrow
-				side="top"
-				delayDuration={LEGEND_TOOLTIP_DELAY_MS}
-				disableHoverableContent
-				tooltipContentProps={{ className: styles.rowTooltip }}
-			>
-				<span className={styles.label}>{label}</span>
-			</TooltipSimple>
-			<div className={styles.actions}>
-				<TooltipSimple
-					title={scopeActionLabel}
-					arrow
-					side="top"
-					delayDuration={LEGEND_TOOLTIP_DELAY_MS}
-					disableHoverableContent
-					tooltipContentProps={{ className: styles.rowTooltip }}
-				>
-					{/* Radix's asChild merge strips the button's own data-testid. */}
-					<span className={styles.actionTrigger}>
-						<Button
-							variant="ghost"
-							color="secondary"
-							size="sm"
-							className={cx(styles.actionButton, styles.scopeButton)}
-							onClick={handleScopeClick}
-							aria-label={scopeActionLabel}
-							testId={`legend-scope-${seriesIndex}`}
-						>
-							{isShowAllAction ? 'All' : 'Only'}
-						</Button>
-					</span>
-				</TooltipSimple>
-				{showCopy && (
-					<CopyButton
-						value={label}
-						size={13}
-						className={styles.actionButton}
-						ariaLabel={`Copy ${label}`}
-						testId={`legend-copy-${seriesIndex}`}
-					/>
-				)}
-			</div>
-		</div>
-	);
-}
-
-export default memo(LegendRow);

frontend/src/lib/uPlotV2/components/Legend/LegendToolbar.module.scss

@@ -1,35 +0,0 @@
-.toolbar {
-	display: flex;
-	align-items: center;
-	flex-wrap: wrap;
-	gap: var(--spacing-5, 10px);
-	padding: 0 var(--spacing-4) var(--spacing-5, 10px);
-	flex-shrink: 0;
-
-	> * {
-		flex: 0 1 auto;
-	}
-}
-
-.status {
-	// Wraps rather than losing the count at its end.
-	min-width: 0;
-	font-family: var(--font-mono);
-	font-size: var(--periscope-font-size-small);
-	color: var(--l3-foreground);
-}
-
-.searchContainer {
-	flex-shrink: 0;
-	width: 100%;
-	padding-right: var(--spacing-4);
-	padding-bottom: var(--spacing-5, 10px);
-}
-
-.searchInput {
-	font-size: var(--font-size-xs);
-}
-
-.searchIcon {
-	color: var(--l3-foreground);
-}

frontend/src/lib/uPlotV2/components/Legend/LegendToolbar.tsx

@@ -1,56 +0,0 @@
-import { ChangeEvent, useCallback } from 'react';
-import { Input } from 'antd';
-import { Search } from '@signozhq/icons';
-
-import styles from './LegendToolbar.module.scss';
-
-export interface LegendToolbarProps {
-	visibleCount: number;
-	totalCount: number;
-	/** Search is intrinsic to the right-positioned legend. */
-	showFilter: boolean;
-	filterQuery: string;
-	onFilterQueryChange: (query: string) => void;
-}
-
-/** Legend chrome: the series search box and the "Showing N of M" readout. */
-export default function LegendToolbar({
-	visibleCount,
-	totalCount,
-	showFilter,
-	filterQuery,
-	onFilterQueryChange,
-}: LegendToolbarProps): JSX.Element {
-	const handleFilterChange = useCallback(
-		(event: ChangeEvent<HTMLInputElement>): void =>
-			onFilterQueryChange(event.target.value),
-		[onFilterQueryChange],
-	);
-
-	return (
-		<>
-			{showFilter && (
-				<div className={styles.searchContainer}>
-					<Input
-						allowClear
-						prefix={<Search size={12} className={styles.searchIcon} />}
-						placeholder="Search..."
-						value={filterQuery}
-						onChange={handleFilterChange}
-						className={styles.searchInput}
-						data-testid="legend-search-input"
-					/>
-				</div>
-			)}
-			<div className={styles.toolbar}>
-				<span
-					className={styles.status}
-					aria-live="polite"
-					data-testid="legend-status"
-				>
-					{`Showing ${visibleCount} of ${totalCount} series`}
-				</span>
-			</div>
-		</>
-	);
-}

frontend/src/lib/uPlotV2/components/Legend/UPlotLegend.tsx

@@ -8,8 +8,8 @@ import Legend from './Legend';
 
 /**
  * uPlot legend controller. Derives the legend items + focus/visibility state
- * from the chart config (useLegendsSync) and the series interactions from the
- * plot context (useLegendActions), then renders the presentational Legend.
+ * from the chart config (useLegendsSync) and the toggle/focus interactions from
+ * the plot context (useLegendActions), then renders the presentational Legend.
  * Must be rendered inside a PlotContextProvider.
  */
 export default function UPlotLegend({
@@ -17,8 +17,13 @@ export default function UPlotLegend({
 	config,
 	averageLegendWidth,
 }: UPlotLegendProps): JSX.Element {
-	const { legendItemsMap, focusedSeriesIndex } = useLegendsSync({ config });
-	const onAction = useLegendActions();
+	const { legendItemsMap, focusedSeriesIndex, setFocusedSeriesIndex } =
+		useLegendsSync({ config });
+	const { onLegendClick, onLegendMouseMove, onLegendMouseLeave } =
+		useLegendActions({
+			setFocusedSeriesIndex,
+			focusedSeriesIndex,
+		});
 
 	const items = useMemo(() => Object.values(legendItemsMap), [legendItemsMap]);
 
@@ -28,7 +33,9 @@ export default function UPlotLegend({
 			position={position}
 			averageLegendWidth={averageLegendWidth}
 			focusedSeriesIndex={focusedSeriesIndex}
-			onAction={onAction}
+			onClick={onLegendClick}
+			onMouseMove={onLegendMouseMove}
+			onMouseLeave={onLegendMouseLeave}
 		/>
 	);
 }

frontend/src/lib/uPlotV2/components/Legend/__tests__/UPlotLegend.test.tsx

@@ -1,419 +0,0 @@
-import React from 'react';
-import { render, RenderResult, screen } from '@testing-library/react';
-import userEvent from '@testing-library/user-event';
-import { TooltipProvider } from '@signozhq/ui/tooltip';
-import { LegendItem } from 'lib/uPlotV2/config/types';
-import useLegendsSync from 'lib/uPlotV2/hooks/useLegendsSync';
-
-import { useLegendActions } from '../../../hooks/useLegendActions';
-import UPlotLegend from '../UPlotLegend';
-import { LegendAction, LegendActionPayload, LegendPosition } from '../../types';
-
-jest.mock('react-virtuoso', () => ({
-	VirtuosoGrid: ({
-		data,
-		itemContent,
-		className,
-	}: {
-		data: LegendItem[];
-		itemContent: (index: number, item: LegendItem) => React.ReactNode;
-		className?: string;
-	}): JSX.Element => (
-		<div data-testid="virtuoso-grid" className={className}>
-			{data.map((item, index) => (
-				<div key={item.seriesIndex ?? index} data-testid="legend-item-wrapper">
-					{itemContent(index, item)}
-				</div>
-			))}
-		</div>
-	),
-}));
-
-jest.mock('lib/uPlotV2/hooks/useLegendsSync');
-jest.mock('lib/uPlotV2/hooks/useLegendActions');
-
-const mockUseLegendsSync = useLegendsSync as jest.MockedFunction<
-	typeof useLegendsSync
->;
-const mockUseLegendActions = useLegendActions as jest.MockedFunction<
-	typeof useLegendActions
->;
-
-/** The payloads of one action type, in dispatch order. */
-const dispatched = (
-	onAction: jest.Mock,
-	type: LegendAction,
-): LegendActionPayload[] =>
-	onAction.mock.calls
-		.map(([payload]) => payload as LegendActionPayload)
-		.filter((payload) => payload.type === type);
-
-describe('UPlotLegend', () => {
-	const baseLegendItemsMap = {
-		0: {
-			seriesIndex: 0,
-			label: 'A',
-			show: true,
-			color: '#ff0000',
-		},
-		1: {
-			seriesIndex: 1,
-			label: 'B',
-			show: false,
-			color: '#00ff00',
-		},
-		2: {
-			seriesIndex: 2,
-			label: 'C',
-			show: true,
-			color: '#0000ff',
-		},
-	};
-
-	let onAction: jest.Mock;
-
-	beforeEach(() => {
-		onAction = jest.fn();
-
-		mockUseLegendsSync.mockReturnValue({
-			legendItemsMap: baseLegendItemsMap,
-			focusedSeriesIndex: 1,
-			setFocusedSeriesIndex: jest.fn(),
-		});
-
-		mockUseLegendActions.mockReturnValue(onAction);
-	});
-
-	afterEach(() => {
-		jest.clearAllMocks();
-	});
-
-	const renderLegend = (position?: LegendPosition): RenderResult =>
-		render(
-			<TooltipProvider>
-				<UPlotLegend
-					position={position}
-					// config is consumed by the mocked useLegendsSync hook, not directly
-					config={{} as any}
-				/>
-			</TooltipProvider>,
-		);
-
-	describe('layout and position', () => {
-		it('renders the search input on a RIGHT legend', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			expect(screen.getByTestId('legend-search-input')).toBeInTheDocument();
-		});
-
-		it('keeps a BOTTOM legend bare — its two rows all go to series', () => {
-			renderLegend();
-
-			expect(screen.queryByTestId('legend-search-input')).not.toBeInTheDocument();
-			expect(screen.queryByTestId('legend-status')).not.toBeInTheDocument();
-			// The row interactions are the same in both placements.
-			expect(screen.getByTestId('legend-item-0')).toBeInTheDocument();
-			expect(screen.getByTestId('legend-scope-0')).toBeInTheDocument();
-		});
-
-		it('renders the marker with the series colour, filled only when shown', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			expect(
-				document.querySelector(
-					'[data-legend-item-id="0"] [data-is-legend-marker="true"]',
-				),
-			).toHaveStyle({
-				'border-color': '#ff0000',
-				'background-color': '#ff0000',
-			});
-			// Hidden series read as an empty checkbox.
-			expect(
-				document.querySelector(
-					'[data-legend-item-id="1"] [data-is-legend-marker="true"]',
-				),
-			).toHaveStyle({ 'background-color': 'transparent' });
-		});
-
-		it('renders all legend items in the grid by default', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			expect(screen.getByTestId('virtuoso-grid')).toBeInTheDocument();
-			expect(screen.getByText('A')).toBeInTheDocument();
-			expect(screen.getByText('B')).toBeInTheDocument();
-			expect(screen.getByText('C')).toBeInTheDocument();
-		});
-	});
-
-	describe('status readout', () => {
-		it('reports how many series are showing', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			expect(screen.getByTestId('legend-status')).toHaveTextContent(
-				'Showing 2 of 3 series',
-			);
-		});
-	});
-
-	describe('filter behavior', () => {
-		it('filters legend items based on the query (case-insensitive)', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			await user.type(screen.getByTestId('legend-search-input'), 'a');
-
-			expect(screen.getByText('A')).toBeInTheDocument();
-			expect(screen.queryByText('B')).not.toBeInTheDocument();
-			expect(screen.queryByText('C')).not.toBeInTheDocument();
-		});
-
-		it('shows the empty state when nothing matches', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			await user.type(screen.getByTestId('legend-search-input'), 'network');
-
-			expect(
-				screen.getByText(/No series found matching "network"/i),
-			).toBeInTheDocument();
-			expect(screen.queryByTestId('virtuoso-grid')).not.toBeInTheDocument();
-		});
-
-		it('ignores a whitespace-only query', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			await user.type(screen.getByTestId('legend-search-input'), '   ');
-
-			expect(
-				screen.queryByText(/No series found matching/i),
-			).not.toBeInTheDocument();
-			expect(screen.getByText('A')).toBeInTheDocument();
-			expect(screen.getByText('B')).toBeInTheDocument();
-			expect(screen.getByText('C')).toBeInTheDocument();
-		});
-	});
-
-	describe('row interactions', () => {
-		const allShownItemsMap = {
-			0: { ...baseLegendItemsMap[0] },
-			1: { ...baseLegendItemsMap[1], show: true },
-			2: { ...baseLegendItemsMap[2] },
-		};
-
-		const mockAllShown = (): void => {
-			mockUseLegendsSync.mockReturnValue({
-				legendItemsMap: allShownItemsMap,
-				focusedSeriesIndex: null,
-				setFocusedSeriesIndex: jest.fn(),
-			});
-		};
-
-		it('isolates the series when everything is showing', async () => {
-			const user = userEvent.setup();
-			mockAllShown();
-			renderLegend(LegendPosition.RIGHT);
-
-			await user.click(screen.getByText('A'));
-
-			// Nothing the user can see is there to exclude, so the click means Only.
-			expect(dispatched(onAction, LegendAction.SHOW_ONLY)).toStrictEqual([
-				{ type: LegendAction.SHOW_ONLY, seriesIndex: 0 },
-			]);
-			expect(dispatched(onAction, LegendAction.TOGGLE)).toHaveLength(0);
-		});
-
-		it('toggles the series once something is already hidden', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			await user.click(screen.getByText('A'));
-
-			expect(dispatched(onAction, LegendAction.TOGGLE)).toStrictEqual([
-				{ type: LegendAction.TOGGLE, seriesIndex: 0 },
-			]);
-			expect(dispatched(onAction, LegendAction.SHOW_ONLY)).toHaveLength(0);
-		});
-
-		it('excludes just that series when its marker is clicked', async () => {
-			const user = userEvent.setup();
-			mockAllShown();
-			renderLegend(LegendPosition.RIGHT);
-
-			await user.click(screen.getByTestId('legend-marker-0'));
-
-			// The marker is the one way to exclude a single series while
-			// everything is showing — the row click isolates instead.
-			expect(dispatched(onAction, LegendAction.TOGGLE)).toStrictEqual([
-				{ type: LegendAction.TOGGLE, seriesIndex: 0 },
-			]);
-			expect(dispatched(onAction, LegendAction.SHOW_ONLY)).toHaveLength(0);
-		});
-
-		it('stops the marker offering to hide the last series showing', () => {
-			mockUseLegendsSync.mockReturnValue({
-				legendItemsMap: {
-					0: { ...baseLegendItemsMap[0] },
-					1: { ...baseLegendItemsMap[1] },
-					2: { ...baseLegendItemsMap[2], show: false },
-				},
-				focusedSeriesIndex: null,
-				setFocusedSeriesIndex: jest.fn(),
-			});
-			renderLegend(LegendPosition.RIGHT);
-
-			expect(screen.getByTestId('legend-marker-0')).toBeDisabled();
-			expect(screen.getByTestId('legend-marker-1')).toBeEnabled();
-		});
-
-		it('labels the marker with what clicking it does', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			expect(screen.getByTestId('legend-marker-0')).toHaveAttribute(
-				'aria-label',
-				'Hide A',
-			);
-			expect(screen.getByTestId('legend-marker-1')).toHaveAttribute(
-				'aria-label',
-				'Show B',
-			);
-		});
-
-		it('adds the clicked series to the selection while one is alone', async () => {
-			const user = userEvent.setup();
-			mockUseLegendsSync.mockReturnValue({
-				legendItemsMap: {
-					0: { ...baseLegendItemsMap[0] },
-					1: { ...baseLegendItemsMap[1] },
-					2: { ...baseLegendItemsMap[2], show: false },
-				},
-				focusedSeriesIndex: null,
-				setFocusedSeriesIndex: jest.fn(),
-			});
-			renderLegend(LegendPosition.RIGHT);
-
-			// Series 0 is showing alone; clicking another row builds the selection
-			// up rather than moving the isolation.
-			await user.click(screen.getByText('B'));
-
-			expect(dispatched(onAction, LegendAction.TOGGLE)).toStrictEqual([
-				{ type: LegendAction.TOGGLE, seriesIndex: 1 },
-			]);
-			expect(dispatched(onAction, LegendAction.SHOW_ONLY)).toHaveLength(0);
-		});
-
-		it('toggles the series on Enter and Space', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			const row = screen.getByTestId('legend-item-0');
-			row.focus();
-			await user.keyboard('{Enter}');
-			await user.keyboard(' ');
-
-			expect(dispatched(onAction, LegendAction.TOGGLE)).toStrictEqual([
-				{ type: LegendAction.TOGGLE, seriesIndex: 0 },
-				{ type: LegendAction.TOGGLE, seriesIndex: 0 },
-			]);
-		});
-
-		it('reflects visibility on the row for assistive tech', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			expect(screen.getByTestId('legend-item-0')).toHaveAttribute(
-				'aria-checked',
-				'true',
-			);
-			expect(screen.getByTestId('legend-item-1')).toHaveAttribute(
-				'aria-checked',
-				'false',
-			);
-		});
-
-		it('restores every series from All without also toggling the row', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			// Series 0 is shown while B is hidden, so its action is All.
-			await user.click(screen.getByTestId('legend-scope-0'));
-
-			expect(dispatched(onAction, LegendAction.SHOW_ALL)).toHaveLength(1);
-			expect(dispatched(onAction, LegendAction.TOGGLE)).toHaveLength(0);
-			expect(dispatched(onAction, LegendAction.SHOW_ONLY)).toHaveLength(0);
-		});
-
-		it('isolates the series from Only on a hidden row', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			await user.click(screen.getByTestId('legend-scope-1'));
-
-			expect(dispatched(onAction, LegendAction.SHOW_ONLY)).toStrictEqual([
-				{ type: LegendAction.SHOW_ONLY, seriesIndex: 1 },
-			]);
-			expect(dispatched(onAction, LegendAction.TOGGLE)).toHaveLength(0);
-		});
-
-		it('highlights the hovered series and clears it on leave', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			const row = screen.getByTestId('legend-item-0');
-			await user.hover(row);
-			expect(onAction).toHaveBeenCalledWith({
-				type: LegendAction.HOVER,
-				seriesIndex: 0,
-			});
-
-			await user.unhover(row);
-			expect(onAction).toHaveBeenCalledWith({
-				type: LegendAction.HOVER,
-				seriesIndex: null,
-			});
-		});
-	});
-
-	describe('one-series state', () => {
-		const soleShownItemsMap = {
-			0: { ...baseLegendItemsMap[0] },
-			1: { ...baseLegendItemsMap[1] },
-			2: { ...baseLegendItemsMap[2], show: false },
-		};
-
-		beforeEach(() => {
-			mockUseLegendsSync.mockReturnValue({
-				legendItemsMap: soleShownItemsMap,
-				focusedSeriesIndex: null,
-				setFocusedSeriesIndex: jest.fn(),
-			});
-		});
-
-		it('offers All on the shown row and Only on the hidden ones', () => {
-			renderLegend(LegendPosition.RIGHT);
-
-			expect(screen.getByTestId('legend-scope-0')).toHaveTextContent('All');
-			expect(screen.getByTestId('legend-scope-1')).toHaveTextContent('Only');
-			expect(screen.getByTestId('legend-scope-2')).toHaveTextContent('Only');
-		});
-
-		it('restores everything from All', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			await user.click(screen.getByTestId('legend-scope-0'));
-
-			expect(dispatched(onAction, LegendAction.SHOW_ALL)).toHaveLength(1);
-		});
-
-		it('restores everything when the row showing alone is clicked again', async () => {
-			const user = userEvent.setup();
-			renderLegend(LegendPosition.RIGHT);
-
-			await user.click(screen.getByText('A'));
-
-			expect(dispatched(onAction, LegendAction.SHOW_ALL)).toHaveLength(1);
-			expect(dispatched(onAction, LegendAction.TOGGLE)).toHaveLength(0);
-			expect(dispatched(onAction, LegendAction.SHOW_ONLY)).toHaveLength(0);
-		});
-	});
-});

frontend/src/lib/uPlotV2/components/Legend/__tests__/utils.test.ts

@@ -1,45 +0,0 @@
-import { LegendItem } from 'lib/uPlotV2/config/types';
-
-import { filterLegendItems, getShownSeriesState } from '../utils';
-
-const items = (shown: boolean[]): LegendItem[] =>
-	shown.map((show, index) => ({
-		seriesIndex: index + 1,
-		label: `series-${index}`,
-		color: '#000',
-		show,
-	}));
-
-describe('getShownSeriesState', () => {
-	it('counts the shown series', () => {
-		expect(getShownSeriesState(items([true, false, true]))).toStrictEqual({
-			visibleCount: 2,
-			soleShownSeriesIndex: null,
-		});
-	});
-
-	it('names the series when exactly one is shown', () => {
-		expect(getShownSeriesState(items([false, true, false]))).toStrictEqual({
-			visibleCount: 1,
-			soleShownSeriesIndex: 2,
-		});
-	});
-
-	it('reports nothing shown', () => {
-		expect(getShownSeriesState(items([false, false]))).toStrictEqual({
-			visibleCount: 0,
-			soleShownSeriesIndex: null,
-		});
-	});
-});
-
-describe('filterLegendItems', () => {
-	it('matches case-insensitively on the label', () => {
-		const filtered = filterLegendItems(items([true, true, true]), 'SERIES-1');
-		expect(filtered.map((item) => item.label)).toStrictEqual(['series-1']);
-	});
-
-	it('returns every item for a blank query', () => {
-		expect(filterLegendItems(items([true, true]), '   ')).toHaveLength(2);
-	});
-});

frontend/src/lib/uPlotV2/components/Legend/constants.ts

@@ -1,20 +0,0 @@
-/** Widest a single legend item is allowed to get when sizing the legend grid. */
-export const MAX_LEGEND_WIDTH = 240;
-
-/**
- * Enough for a row to contain its own hover actions, which a short label would
- * otherwise size a column too narrow for. Little room for the label is intended.
- */
-export const MIN_LEGEND_ITEM_WIDTH = 110;
-
-/** Marker + row padding, on top of the estimated label width. */
-export const LEGEND_ITEM_EXTRA_WIDTH = 16;
-
-/** Must match `.row`'s height and the grid's row gap, or the reserved
- * rectangle clips a row. */
-export const LEGEND_ROW_HEIGHT = 28;
-export const LEGEND_ROW_GAP = 2;
-export const LEGEND_MAX_BOTTOM_ROWS = 2;
-
-/** Hover delay before a row's full-name tooltip opens. */
-export const LEGEND_TOOLTIP_DELAY_MS = 500;

frontend/src/lib/uPlotV2/components/Legend/utils.ts

@@ -1,34 +0,0 @@
-import { LegendItem } from 'lib/uPlotV2/config/types';
-
-export interface ShownSeriesState {
-	visibleCount: number;
-	/** The series index when exactly one series is shown, else null. */
-	soleShownSeriesIndex: number | null;
-}
-
-/**
- * Driven by what is actually shown, never a remembered isolation: hiding series
- * one at a time down to a single one is the same state as "Only".
- */
-export function getShownSeriesState(items: LegendItem[]): ShownSeriesState {
-	const shown = items.filter((item) => item.show);
-
-	return {
-		visibleCount: shown.length,
-		soleShownSeriesIndex: shown.length === 1 ? shown[0].seriesIndex : null,
-	};
-}
-
-export function filterLegendItems(
-	items: LegendItem[],
-	query: string,
-): LegendItem[] {
-	const normalisedQuery = query.trim().toLowerCase();
-	if (!normalisedQuery) {
-		return items;
-	}
-
-	return items.filter((item) =>
-		item.label?.toLowerCase().includes(normalisedQuery),
-	);
-}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/HeatmapBucketList.tsx

@@ -0,0 +1,29 @@
+import cx from 'classnames';
+
+import { formatCount, HeatmapBucketRow } from './heatmapTooltipContent';
+
+import Styles from './HeatmapTooltip.module.scss';
+
+/** The buckets either side of the hovered one, so a mode reads as a shape rather
+ *  than a single number. */
+export default function HeatmapBucketList({
+	rows,
+}: {
+	rows: HeatmapBucketRow[];
+}): JSX.Element {
+	return (
+		<div className={Styles.rows} data-testid="heatmap-tooltip-buckets">
+			{rows.map((row) => (
+				<div
+					key={row.label}
+					className={cx(Styles.row, { [Styles.rowHovered]: row.isHovered })}
+					data-hovered={row.isHovered}
+					data-testid="heatmap-tooltip-bucket-row"
+				>
+					<span className={Styles.rowLabel}>{row.label}</span>
+					<span className={Styles.rowValue}>{formatCount(row.count)}</span>
+				</div>
+			))}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/HeatmapContributionList.tsx

@@ -0,0 +1,39 @@
+import {
+	formatCount,
+	formatPercent,
+	HeatmapContributionRow,
+} from './heatmapTooltipContent';
+
+import Styles from './HeatmapTooltip.module.scss';
+
+/** Only shown when the cell sums more than one group. */
+export default function HeatmapContributionList({
+	rows,
+	groupByLabel,
+}: {
+	rows: HeatmapContributionRow[];
+	/** The `groupBy` keys these rows are by. */
+	groupByLabel: string;
+}): JSX.Element {
+	return (
+		<div className={Styles.rows} data-testid="heatmap-tooltip-contribution">
+			{groupByLabel && <span className={Styles.section}>{groupByLabel}</span>}
+			{rows.map((row) => (
+				<div
+					key={row.label}
+					className={Styles.row}
+					data-testid="heatmap-tooltip-contribution-row"
+				>
+					<span
+						className={Styles.marker}
+						style={{ background: row.color }}
+						data-is-legend-marker={true}
+					/>
+					<span className={Styles.rowLabel}>{row.label}</span>
+					<span className={Styles.rowValue}>{formatCount(row.count)}</span>
+					<span className={Styles.rowPercent}>{formatPercent(row.percent)}</span>
+				</div>
+			))}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/HeatmapTooltip.module.scss

@@ -0,0 +1,151 @@
+// Surface matches the shared Tooltip exactly — same tokens, same radius, no
+// shadow (the plugin's portal wrapper is transparent and paints nothing).
+//
+// Padding lives on the sections rather than here, also matching the shared
+// tooltip: TooltipFooter draws its own dashed top border, background and bottom
+// corner radius, so it has to reach the container edges.
+.container {
+	font-family: 'Inter';
+	font-size: 12px;
+	background: var(--l2-background);
+	-webkit-font-smoothing: antialiased;
+	color: var(--l2-foreground);
+	border-radius: 6px;
+	border: 1px solid var(--l2-border);
+	display: flex;
+	flex-direction: column;
+	min-width: 220px;
+
+	&.pinned {
+		border-color: var(--ring);
+	}
+}
+
+// Separates the cell identity from whichever question the second block answers.
+.divider {
+	display: block;
+	width: 100%;
+	height: 1px;
+	background-color: var(--l2-border);
+}
+
+.identity {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-2);
+	padding: var(--spacing-4) var(--spacing-4) var(--spacing-3);
+}
+
+.header {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: var(--spacing-6);
+	font-size: 11px;
+	color: var(--text-vanilla-400);
+	font-variant-numeric: tabular-nums;
+}
+
+.filter {
+	display: flex;
+	align-items: center;
+	gap: 5px;
+	min-width: 0;
+}
+
+// Hollow ring, matching the legend's unselected marker — this names the filter the
+// grid is under, it is not a colour key.
+.filterMarker {
+	width: 9px;
+	height: 9px;
+	border-radius: 50%;
+	border: 2px solid currentColor;
+	flex-shrink: 0;
+}
+
+.filterLabel {
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.title {
+	display: flex;
+	align-items: baseline;
+	justify-content: space-between;
+	gap: var(--spacing-8);
+}
+
+.titleBucket {
+	font-size: 13px;
+	font-weight: 600;
+	color: var(--text-vanilla-100);
+}
+
+.titleCount {
+	font-size: 13px;
+	font-weight: 600;
+	color: var(--text-vanilla-100);
+	font-variant-numeric: tabular-nums;
+}
+
+.rows {
+	display: flex;
+	flex-direction: column;
+	gap: var(--spacing-1);
+	padding: var(--spacing-3) var(--spacing-4);
+}
+
+.section {
+	font-size: 10px;
+	letter-spacing: 0.06em;
+	text-transform: uppercase;
+	color: var(--text-vanilla-400);
+	padding: 0 var(--spacing-2) var(--spacing-1);
+}
+
+.row {
+	display: flex;
+	align-items: center;
+	gap: var(--spacing-4);
+	padding: var(--spacing-1) var(--spacing-2);
+	border-radius: 3px;
+	font-size: 12px;
+	color: var(--text-vanilla-400);
+	font-variant-numeric: tabular-nums;
+}
+
+// The hovered bucket is the one the cursor is on; lift it out of the neighbours.
+.rowHovered {
+	background: var(--l3-background);
+	color: var(--text-vanilla-100);
+	font-weight: 500;
+}
+
+.rowLabel {
+	flex: 1;
+	min-width: 0;
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.rowValue {
+	flex: 0 0 auto;
+	text-align: right;
+}
+
+.rowPercent {
+	flex: 0 0 auto;
+	min-width: 40px;
+	text-align: right;
+	color: var(--text-vanilla-400);
+	opacity: 0.75;
+}
+
+.marker {
+	width: 8px;
+	height: 8px;
+	border-radius: 50%;
+	flex-shrink: 0;
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/HeatmapTooltip.tsx

@@ -0,0 +1,181 @@
+import { useMemo } from 'react';
+import cx from 'classnames';
+import {
+	resolveColumnIndex,
+	resolveRowIndex,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import { useTimezone } from 'providers/Timezone';
+
+import { HeatmapTooltipProps } from '../../../types';
+import HeatmapBucketList from './HeatmapBucketList';
+import HeatmapContributionList from './HeatmapContributionList';
+import {
+	buildBucketRows,
+	buildContributionRows,
+	formatBucketLabel,
+	formatColumnRange,
+	formatCount,
+	formatGroupFilter,
+	HeatmapTooltipBody,
+	resolveGroupByLabel,
+	resolveTooltipBody,
+} from './heatmapTooltipContent';
+
+import Styles from './HeatmapTooltip.module.scss';
+
+/**
+ * The cell identity is the same in every state; the second block answers whichever
+ * question the panel state leaves open (see `resolveTooltipBody`). Purpose-built
+ * rather than composed from the shared `Tooltip`, which renders a flat list of
+ * series values — none of these states is that shape.
+ *
+ * The cell comes from the live cursor, not a prop: uPlot's `cursor.idx` snaps to
+ * the nearest timestamp, so half of every column would report its neighbour.
+ */
+export default function HeatmapTooltip({
+	uPlotInstance,
+	yAxis,
+	step,
+	series,
+	visibleGroups,
+	groupColor,
+	yAxisUnit,
+	decimalPrecision,
+	timezone,
+	isPinned,
+	dismiss,
+	renderTooltipFooter,
+}: HeatmapTooltipProps): JSX.Element | null {
+	const { timezone: userTimezone } = useTimezone();
+	const resolvedTimezone = timezone?.value ?? userTimezone.value;
+
+	// Read outside the memo: uPlot mutates the same instance on every move, so
+	// keying off the instance alone would freeze the cell.
+	const { left = -10, top = -10 } = uPlotInstance.cursor;
+
+	const cell = useMemo(() => {
+		if (left < 0 || top < 0) {
+			return null;
+		}
+		const timestamps = uPlotInstance.data[0] as ArrayLike<number>;
+		const column = resolveColumnIndex(
+			timestamps,
+			uPlotInstance.posToVal(left, 'x'),
+			step,
+		);
+		const row = resolveRowIndex(yAxis.edges, uPlotInstance.posToVal(top, 'y'));
+		if (column === null || row === null) {
+			return null;
+		}
+		return {
+			row,
+			column,
+			timestamp: timestamps[column],
+			count:
+				(uPlotInstance.data[row + 1] as Array<number | null> | undefined)?.[
+					column
+				] ?? null,
+		};
+	}, [left, top, uPlotInstance, yAxis, step]);
+
+	// The cell sums the enabled groups, so those are what a breakdown must cover.
+	const visible = useMemo(
+		() => series.filter((entry) => visibleGroups.includes(entry.label)),
+		[series, visibleGroups],
+	);
+	const body = resolveTooltipBody(visible.length);
+
+	const bucketRows = useMemo(() => {
+		if (!cell || body !== HeatmapTooltipBody.Buckets) {
+			return [];
+		}
+		return buildBucketRows({
+			counts: uPlotInstance.data.slice(1) as Array<
+				ArrayLike<number | null> | undefined
+			>,
+			yAxis,
+			row: cell.row,
+			column: cell.column,
+			yAxisUnit,
+			decimalPrecision,
+		});
+	}, [cell, body, uPlotInstance, yAxis, yAxisUnit, decimalPrecision]);
+
+	const contributionRows = useMemo(() => {
+		if (!cell || body !== HeatmapTooltipBody.Contribution) {
+			return [];
+		}
+		return buildContributionRows({
+			series: visible,
+			timestamp: cell.timestamp,
+			row: cell.row,
+			color: groupColor,
+		});
+	}, [cell, body, visible, groupColor]);
+
+	if (!cell) {
+		return null;
+	}
+
+	// A single enabled group out of several means the legend has isolated it.
+	const isolated =
+		series.length > 1 && visible.length === 1 ? visible[0] : undefined;
+	const filterLabel = formatGroupFilter(isolated);
+
+	return (
+		<div
+			className={cx(Styles.container, { [Styles.pinned]: isPinned })}
+			data-pinned={isPinned}
+			data-testid="heatmap-tooltip"
+		>
+			<div className={Styles.identity}>
+				<div className={Styles.header}>
+					<span data-testid="heatmap-tooltip-range">
+						{formatColumnRange({
+							start: cell.timestamp,
+							step,
+							timezone: resolvedTimezone,
+						})}
+					</span>
+					{filterLabel && (
+						<span
+							className={Styles.filter}
+							style={{ color: groupColor }}
+							data-testid="heatmap-tooltip-filter"
+						>
+							<span className={Styles.filterMarker} />
+							<span className={Styles.filterLabel}>{filterLabel}</span>
+						</span>
+					)}
+				</div>
+
+				<div className={Styles.title}>
+					<span className={Styles.titleBucket} data-testid="heatmap-tooltip-bucket">
+						{formatBucketLabel({
+							yAxis,
+							row: cell.row,
+							yAxisUnit,
+							decimalPrecision,
+						})}
+					</span>
+					<span className={Styles.titleCount} data-testid="heatmap-tooltip-count">
+						{formatCount(cell.count)}
+					</span>
+				</div>
+			</div>
+
+			<span className={Styles.divider} data-testid="heatmap-tooltip-divider" />
+
+			{body === HeatmapTooltipBody.Contribution ? (
+				<HeatmapContributionList
+					rows={contributionRows}
+					groupByLabel={resolveGroupByLabel(series)}
+				/>
+			) : (
+				<HeatmapBucketList rows={bucketRows} />
+			)}
+
+			{renderTooltipFooter?.({ isPinned, dismiss })}
+		</div>
+	);
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/__tests__/HeatmapTooltip.test.tsx

@@ -0,0 +1,289 @@
+import { resolveHeatmapYAxis } from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import {
+	HeatmapAxisScale,
+	HeatmapSeries,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+import { render, RenderResult, screen } from 'tests/test-utils';
+import type uPlot from 'uplot';
+
+import HeatmapTooltip from '../HeatmapTooltip';
+
+const BOUNDS = [100, 500, 1000, 2500];
+const Y_AXIS = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+const TIMESTAMPS = [1_700_000_000, 1_700_000_300];
+const STEP = 300;
+const PLOT_SIZE = 500;
+const ROW_COUNT = BOUNDS.length + 1;
+
+/** Row 2 is the 500ms–1s bucket the design mock hovers. */
+const HOVERED_ROW = 2;
+
+function seriesFor(
+	group: string,
+	countsAtHoveredRow: [number, number],
+): HeatmapSeries {
+	return {
+		label: `service.name=${group}`,
+		labels: [{ key: 'service.name', value: group }],
+		points: TIMESTAMPS.map((timestamp, column) => ({
+			timestamp,
+			counts: Array.from({ length: ROW_COUNT }, (_, row) =>
+				row === HOVERED_ROW ? countsAtHoveredRow[column] : row * 10,
+			),
+		})),
+	};
+}
+
+const GROUPED: HeatmapSeries[] = [
+	seriesFor('checkout', [355, 300]),
+	seriesFor('frontend', [86, 80]),
+	seriesFor('cart', [14, 10]),
+	seriesFor('payments', [0, 0]),
+];
+
+/** Grid counts, matching what the renderer would have been handed. */
+function gridData(rowTotals: number[]): uPlot.AlignedData {
+	return [
+		TIMESTAMPS,
+		...Array.from({ length: ROW_COUNT }, (_, row) => [
+			rowTotals[row] ?? row * 40,
+			rowTotals[row] ?? row * 40,
+		]),
+	] as unknown as uPlot.AlignedData;
+}
+
+// Totals chosen to match the mock: 2 / 92 / 455 / 269 / 10 bottom-up.
+const ROW_TOTALS = [10, 269, 455, 92, 2];
+
+function createFakePlot(): uPlot {
+	const xSpan = TIMESTAMPS[TIMESTAMPS.length - 1] + STEP - TIMESTAMPS[0];
+	const ySpan = Y_AXIS.max - Y_AXIS.min;
+	// Aim the cursor at the middle of the hovered row, first column.
+	const rowMid = (Y_AXIS.edges[HOVERED_ROW] + Y_AXIS.edges[HOVERED_ROW + 1]) / 2;
+	const top = PLOT_SIZE * (1 - (rowMid - Y_AXIS.min) / ySpan);
+
+	return {
+		data: gridData(ROW_TOTALS),
+		cursor: { left: PLOT_SIZE * 0.25, top },
+		posToVal: (pos: number, scaleKey: string): number =>
+			scaleKey === 'x'
+				? TIMESTAMPS[0] + (pos / PLOT_SIZE) * xSpan
+				: Y_AXIS.min + ((PLOT_SIZE - pos) / PLOT_SIZE) * ySpan,
+	} as unknown as uPlot;
+}
+
+function renderTooltip(
+	overrides: Partial<React.ComponentProps<typeof HeatmapTooltip>> = {},
+): RenderResult {
+	return render(
+		<HeatmapTooltip
+			id="panel-1"
+			uPlotInstance={createFakePlot()}
+			dataIndexes={[]}
+			seriesIndex={null}
+			isPinned={false}
+			dismiss={jest.fn()}
+			viaSync={false}
+			yAxis={Y_AXIS}
+			step={STEP}
+			series={GROUPED}
+			visibleGroups={GROUPED.map((entry) => entry.label)}
+			groupColor="#fcfdbf"
+			yAxisUnit="ms"
+			{...overrides}
+		/>,
+	);
+}
+
+describe('HeatmapTooltip — cell identity', () => {
+	it('heads with the time span the column covers, not a single instant', () => {
+		renderTooltip();
+
+		expect(screen.getByTestId('heatmap-tooltip-range').textContent).toMatch(
+			/^\d{2}:\d{2} → \d{2}:\d{2}$/,
+		);
+	});
+
+	it('names the hovered bucket and its count', () => {
+		renderTooltip();
+
+		expect(screen.getByTestId('heatmap-tooltip-bucket')).toHaveTextContent(
+			'500 ms – 1 s',
+		);
+		expect(screen.getByTestId('heatmap-tooltip-count')).toHaveTextContent('455');
+	});
+
+	it('marks the surface as pinned so the border picks up the ring', () => {
+		renderTooltip({ isPinned: true });
+
+		expect(screen.getByTestId('heatmap-tooltip')).toHaveAttribute(
+			'data-pinned',
+			'true',
+		);
+	});
+
+	it('is unpinned by default', () => {
+		renderTooltip();
+
+		expect(screen.getByTestId('heatmap-tooltip')).toHaveAttribute(
+			'data-pinned',
+			'false',
+		);
+	});
+
+	it('separates the cell identity from the block below it', () => {
+		renderTooltip();
+
+		expect(screen.getByTestId('heatmap-tooltip-divider')).toBeInTheDocument();
+	});
+
+	it('renders a footer when the panel supplies one', () => {
+		renderTooltip({
+			renderTooltipFooter: ({ isPinned }): JSX.Element => (
+				<div data-testid="footer">{isPinned ? 'pinned' : 'press P'}</div>
+			),
+		});
+
+		expect(screen.getByTestId('footer')).toHaveTextContent('press P');
+	});
+
+	it('tells the footer when the tooltip is pinned', () => {
+		renderTooltip({
+			isPinned: true,
+			renderTooltipFooter: ({ isPinned }): JSX.Element => (
+				<div data-testid="footer">{isPinned ? 'pinned' : 'press P'}</div>
+			),
+		});
+
+		expect(screen.getByTestId('footer')).toHaveTextContent('pinned');
+	});
+
+	it('renders nothing when the cursor is off the plot', () => {
+		const plot = createFakePlot();
+		(plot as { cursor: unknown }).cursor = { left: -10, top: -10 };
+
+		const { container } = renderTooltip({ uPlotInstance: plot });
+
+		expect(container).toBeEmptyDOMElement();
+	});
+});
+
+describe('HeatmapTooltip — grouped, nothing selected', () => {
+	it('breaks the cell down by group instead of showing neighbours', () => {
+		renderTooltip();
+
+		expect(
+			screen.getByTestId('heatmap-tooltip-contribution'),
+		).toBeInTheDocument();
+		expect(
+			screen.queryByTestId('heatmap-tooltip-buckets'),
+		).not.toBeInTheDocument();
+	});
+
+	it('heads the breakdown with the groupBy key', () => {
+		renderTooltip();
+
+		expect(screen.getByText('service.name')).toBeInTheDocument();
+	});
+
+	it('names each row by value alone and orders by contribution', () => {
+		renderTooltip();
+
+		const rows = screen
+			.getAllByTestId('heatmap-tooltip-contribution-row')
+			.map((row) => row.textContent);
+
+		expect(rows[0]).toContain('checkout');
+		expect(rows[0]).toContain('355');
+		expect(rows[1]).toContain('frontend');
+		expect(rows[2]).toContain('cart');
+	});
+
+	it('shows each group"s share of the cell', () => {
+		renderTooltip();
+
+		const rows = screen.getAllByTestId('heatmap-tooltip-contribution-row');
+		// 355 / 455 = 78%, 86 / 455 = 19%, 14 / 455 = 3.1%
+		expect(rows[0]).toHaveTextContent('78%');
+		expect(rows[1]).toHaveTextContent('19%');
+		expect(rows[2]).toHaveTextContent('3.1%');
+	});
+
+	it('still lists a group that contributed nothing', () => {
+		renderTooltip();
+
+		const rows = screen.getAllByTestId('heatmap-tooltip-contribution-row');
+		expect(rows).toHaveLength(GROUPED.length);
+		expect(rows[3]).toHaveTextContent('payments');
+		expect(rows[3]).toHaveTextContent('0.0%');
+	});
+
+	it('does not name a filter when every group is enabled', () => {
+		renderTooltip();
+
+		expect(
+			screen.queryByTestId('heatmap-tooltip-filter'),
+		).not.toBeInTheDocument();
+	});
+});
+
+describe('HeatmapTooltip — grouped, one enabled', () => {
+	const selected = { visibleGroups: ['service.name=checkout'] };
+
+	it('returns to neighbouring buckets, since contribution is already answered', () => {
+		renderTooltip(selected);
+
+		expect(screen.getByTestId('heatmap-tooltip-buckets')).toBeInTheDocument();
+		expect(
+			screen.queryByTestId('heatmap-tooltip-contribution'),
+		).not.toBeInTheDocument();
+	});
+
+	it('names the active filter', () => {
+		renderTooltip(selected);
+
+		expect(screen.getByTestId('heatmap-tooltip-filter')).toHaveTextContent(
+			'service.name = checkout',
+		);
+	});
+});
+
+describe('HeatmapTooltip — no grouping', () => {
+	const ungrouped = {
+		series: [{ label: '', points: GROUPED[0].points }],
+		visibleGroups: [''],
+	};
+
+	it('shows neighbouring buckets, highest first', () => {
+		renderTooltip(ungrouped);
+
+		const rows = screen
+			.getAllByTestId('heatmap-tooltip-bucket-row')
+			.map((row) => row.textContent);
+
+		// Two buckets either side of 500ms – 1s, reading down the y axis.
+		expect(rows).toHaveLength(5);
+		expect(rows[0]).toContain('> 2.5 s');
+		expect(rows[2]).toContain('500 ms – 1 s');
+		expect(rows[4]).toContain('≤ 100 ms');
+	});
+
+	it('marks the hovered bucket among its neighbours', () => {
+		renderTooltip(ungrouped);
+
+		const hovered = screen
+			.getAllByTestId('heatmap-tooltip-bucket-row')
+			.filter((row) => row.dataset.hovered === 'true');
+
+		expect(hovered).toHaveLength(1);
+		expect(hovered[0]).toHaveTextContent('500 ms – 1 s');
+	});
+
+	it('never breaks down a single series', () => {
+		renderTooltip(ungrouped);
+
+		expect(
+			screen.queryByTestId('heatmap-tooltip-contribution'),
+		).not.toBeInTheDocument();
+	});
+});

frontend/src/lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/heatmapTooltipContent.ts

@@ -0,0 +1,199 @@
+import { PrecisionOption } from 'components/Graph/types';
+import { getToolTipValue } from 'components/Graph/yAxisConfig';
+import { DATE_TIME_FORMATS } from 'constants/dateTimeFormats';
+import dayjs from 'dayjs';
+import { formatRowLabel } from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import {
+	HeatmapSeries,
+	HeatmapYAxis,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+
+/** Rows shown either side of the hovered one. */
+const NEIGHBOUR_SPAN = 2;
+/** Below this share a percentage needs a decimal to stay informative. */
+const PERCENT_DECIMAL_THRESHOLD = 10;
+/** Below this, the header needs seconds to distinguish columns. */
+const SUB_MINUTE_STEP = 60;
+
+export const NO_DATA_LABEL = 'no data';
+
+/**
+ * Which question the second block answers. A cell summed across several groups begs
+ * "which group?"; a cell that is already one series begs "how does this bucket
+ * compare with its neighbours?".
+ */
+export enum HeatmapTooltipBody {
+	Buckets = 'buckets',
+	Contribution = 'contribution',
+}
+
+export interface HeatmapBucketRow {
+	label: string;
+	count: number | null;
+	isHovered: boolean;
+}
+
+export interface HeatmapContributionRow {
+	label: string;
+	color: string;
+	count: number;
+	/** Share of the cell's total, 0..100. */
+	percent: number;
+}
+
+export function resolveTooltipBody(visibleCount: number): HeatmapTooltipBody {
+	// One enabled group contributes the whole cell, so there is nothing to break
+	// down — whether the query is ungrouped or the legend has isolated a group.
+	return visibleCount > 1
+		? HeatmapTooltipBody.Contribution
+		: HeatmapTooltipBody.Buckets;
+}
+
+/** A cell is an interval, so a single instant would misreport which observations
+ *  it contains. The date is left to the x axis directly below. */
+export function formatColumnRange({
+	start,
+	step,
+	timezone,
+}: {
+	/** Column start, in seconds. */
+	start: number;
+	/** Column width, in seconds. */
+	step: number;
+	timezone: string;
+}): string {
+	const format =
+		step < SUB_MINUTE_STEP
+			? DATE_TIME_FORMATS.TIME_SECONDS
+			: DATE_TIME_FORMATS.TIME;
+	const from = dayjs(start * 1000).tz(timezone);
+	const to = dayjs((start + step) * 1000).tz(timezone);
+	return `${from.format(format)} → ${to.format(format)}`;
+}
+
+/** Formatted with the panel's unit. */
+export function formatBucketLabel({
+	yAxis,
+	row,
+	yAxisUnit,
+	decimalPrecision,
+}: {
+	yAxis: HeatmapYAxis;
+	row: number;
+	yAxisUnit?: string;
+	decimalPrecision?: PrecisionOption;
+}): string {
+	const bucket = yAxis.rows[row];
+	if (!bucket) {
+		return '';
+	}
+	return formatRowLabel(bucket, (value) =>
+		getToolTipValue(String(value), yAxisUnit, decimalPrecision),
+	);
+}
+
+export function formatCount(count: number | null): string {
+	return count === null ? NO_DATA_LABEL : count.toLocaleString();
+}
+
+export function formatPercent(percent: number): string {
+	return percent >= PERCENT_DECIMAL_THRESHOLD
+		? `${Math.round(percent)}%`
+		: `${percent.toFixed(1)}%`;
+}
+
+/** Names the group the grid is currently isolated to. */
+export function formatGroupFilter(series: HeatmapSeries | undefined): string {
+	if (!series) {
+		return '';
+	}
+	if (!series.labels?.length) {
+		return series.label;
+	}
+	return series.labels
+		.map((label) => `${label.key} = ${label.value}`)
+		.join(', ');
+}
+
+/** The `groupBy` keys the breakdown is by. */
+export function resolveGroupByLabel(series: HeatmapSeries[]): string {
+	const keys = series[0]?.labels?.map((label) => label.key) ?? [];
+	return keys.join(', ');
+}
+
+function formatSeriesValue(series: HeatmapSeries): string {
+	if (!series.labels?.length) {
+		return series.label;
+	}
+	return series.labels.map((label) => label.value).join(', ');
+}
+
+/** Highest first, so the list reads in the same direction as the y axis. */
+export function buildBucketRows({
+	counts,
+	yAxis,
+	row,
+	column,
+	yAxisUnit,
+	decimalPrecision,
+}: {
+	/** Row-major, as the renderer draws them. */
+	counts: Array<ArrayLike<number | null> | undefined>;
+	yAxis: HeatmapYAxis;
+	row: number;
+	column: number;
+	yAxisUnit?: string;
+	decimalPrecision?: PrecisionOption;
+}): HeatmapBucketRow[] {
+	const formatBucketValue = (value: number): string =>
+		getToolTipValue(String(value), yAxisUnit, decimalPrecision);
+
+	const rows: HeatmapBucketRow[] = [];
+	for (let offset = NEIGHBOUR_SPAN; offset >= -NEIGHBOUR_SPAN; offset -= 1) {
+		const index = row + offset;
+		const bucket = yAxis.rows[index];
+		if (!bucket) {
+			continue;
+		}
+		rows.push({
+			label: formatRowLabel(bucket, formatBucketValue),
+			count: counts[index]?.[column] ?? null,
+			isHovered: offset === 0,
+		});
+	}
+	return rows;
+}
+
+/**
+ * Largest first. Groups that contributed nothing are still listed — that is an
+ * answer, and dropping the row makes the list look truncated.
+ */
+export function buildContributionRows({
+	series,
+	timestamp,
+	row,
+	color,
+}: {
+	/** Only the groups the legend has enabled — they are what the cell sums. */
+	series: HeatmapSeries[];
+	/** Column start, in seconds. */
+	timestamp: number;
+	row: number;
+	color: string;
+}): HeatmapContributionRow[] {
+	const counts = series.map((entry) => {
+		const point = entry.points.find((item) => item.timestamp === timestamp);
+		// Absent or null contributed nothing to the sum, which is what this breaks down.
+		return point?.counts[row] ?? 0;
+	});
+	const total = counts.reduce((sum, count) => sum + count, 0);
+
+	return series
+		.map((entry, index) => ({
+			label: formatSeriesValue(entry),
+			color,
+			count: counts[index],
+			percent: total > 0 ? (counts[index] / total) * 100 : 0,
+		}))
+		.sort((a, b) => b.count - a.count);
+}

frontend/src/lib/uPlotV2/components/Tooltip/components/TooltipItem/TooltipItem.module.scss

@@ -12,11 +12,10 @@
 	}
 }
 
-// Matches the legend row's marker.
 .uplotTooltipItemMarker {
-	border-radius: var(--radius);
+	border-radius: 50%;
 	border-style: solid;
-	border-width: 1.5px;
+	border-width: 2px;
 	width: 12px;
 	height: 12px;
 	box-sizing: border-box;
@@ -31,23 +30,11 @@
 	justify-content: space-between;
 }
 
-// The legend's mono type; the container's Inter stays for the header.
-.uplotTooltipItemLabel,
-.uplotTooltipItemValue {
-	font-family: var(--font-mono);
-	font-size: var(--font-size-xs);
-	letter-spacing: -0.01em;
-}
-
 .uplotTooltipItemLabel {
 	white-space: normal;
 	overflow-wrap: anywhere;
 }
 
-.uplotTooltipItemValue {
-	white-space: nowrap;
-}
-
 .uplotTooltipItemContentSeparator {
 	flex: 1;
 	border-width: 0.5px;

frontend/src/lib/uPlotV2/components/Tooltip/components/TooltipItem/TooltipItem.tsx

@@ -25,7 +25,7 @@ export default function TooltipItem({
 		>
 			<div
 				className={Styles.uplotTooltipItemMarker}
-				style={{ borderColor: item.color, backgroundColor: item.color }}
+				style={{ borderColor: item.color }}
 				data-is-legend-marker={true}
 				data-testid={markerTestId}
 			/>
@@ -39,7 +39,7 @@ export default function TooltipItem({
 					className={Styles.uplotTooltipItemContentSeparator}
 					style={{ borderColor: item.color }}
 				/>
-				<span className={Styles.uplotTooltipItemValue}>{item.tooltipValue}</span>
+				<span>{item.tooltipValue}</span>
 			</div>
 		</div>
 	);

frontend/src/lib/uPlotV2/components/__tests__/UPlotLegend.test.tsx

@@ -0,0 +1,216 @@
+import React from 'react';
+import { render, RenderResult, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { TooltipProvider } from '@signozhq/ui/tooltip';
+import { LegendItem } from 'lib/uPlotV2/config/types';
+import useLegendsSync from 'lib/uPlotV2/hooks/useLegendsSync';
+
+import { useLegendActions } from '../../hooks/useLegendActions';
+import UPlotLegend from '../Legend/UPlotLegend';
+import { LegendPosition } from '../types';
+
+jest.mock('react-virtuoso', () => ({
+	VirtuosoGrid: ({
+		data,
+		itemContent,
+		className,
+	}: {
+		data: LegendItem[];
+		itemContent: (index: number, item: LegendItem) => React.ReactNode;
+		className?: string;
+	}): JSX.Element => (
+		<div data-testid="virtuoso-grid" className={className}>
+			{data.map((item, index) => (
+				<div key={item.seriesIndex ?? index} data-testid="legend-item-wrapper">
+					{itemContent(index, item)}
+				</div>
+			))}
+		</div>
+	),
+}));
+
+jest.mock('lib/uPlotV2/hooks/useLegendsSync');
+jest.mock('lib/uPlotV2/hooks/useLegendActions');
+
+const mockUseLegendsSync = useLegendsSync as jest.MockedFunction<
+	typeof useLegendsSync
+>;
+const mockUseLegendActions = useLegendActions as jest.MockedFunction<
+	typeof useLegendActions
+>;
+
+describe('UPlotLegend', () => {
+	const baseLegendItemsMap = {
+		0: {
+			seriesIndex: 0,
+			label: 'A',
+			show: true,
+			color: '#ff0000',
+		},
+		1: {
+			seriesIndex: 1,
+			label: 'B',
+			show: false,
+			color: '#00ff00',
+		},
+		2: {
+			seriesIndex: 2,
+			label: 'C',
+			show: true,
+			color: '#0000ff',
+		},
+	};
+
+	let onLegendClick: jest.Mock;
+	let onLegendMouseMove: jest.Mock;
+	let onLegendMouseLeave: jest.Mock;
+	let onFocusSeries: jest.Mock;
+
+	beforeEach(() => {
+		onLegendClick = jest.fn();
+		onLegendMouseMove = jest.fn();
+		onLegendMouseLeave = jest.fn();
+		onFocusSeries = jest.fn();
+
+		mockUseLegendsSync.mockReturnValue({
+			legendItemsMap: baseLegendItemsMap,
+			focusedSeriesIndex: 1,
+			setFocusedSeriesIndex: jest.fn(),
+		});
+
+		mockUseLegendActions.mockReturnValue({
+			onLegendClick,
+			onLegendMouseMove,
+			onLegendMouseLeave,
+			onFocusSeries,
+		});
+	});
+
+	afterEach(() => {
+		jest.clearAllMocks();
+	});
+
+	const renderLegend = (position?: LegendPosition): RenderResult =>
+		render(
+			<TooltipProvider>
+				<UPlotLegend
+					position={position}
+					// config is consumed by the mocked useLegendsSync hook, not directly
+					config={{} as any}
+				/>
+			</TooltipProvider>,
+		);
+
+	describe('layout and position', () => {
+		it('renders search input when legend position is RIGHT', () => {
+			renderLegend(LegendPosition.RIGHT);
+
+			expect(screen.getByTestId('legend-search-input')).toBeInTheDocument();
+		});
+
+		it('does not render search input when legend position is BOTTOM (default)', () => {
+			renderLegend();
+
+			expect(screen.queryByTestId('legend-search-input')).not.toBeInTheDocument();
+		});
+
+		it('renders the marker with the correct border color', () => {
+			renderLegend(LegendPosition.RIGHT);
+
+			const legendMarker = document.querySelector(
+				'[data-legend-item-id="0"] [data-is-legend-marker="true"]',
+			) as HTMLElement;
+
+			expect(legendMarker).toHaveStyle({
+				'border-color': '#ff0000',
+			});
+		});
+
+		it('renders all legend items in the grid by default', () => {
+			renderLegend(LegendPosition.RIGHT);
+
+			expect(screen.getByTestId('virtuoso-grid')).toBeInTheDocument();
+			expect(screen.getByText('A')).toBeInTheDocument();
+			expect(screen.getByText('B')).toBeInTheDocument();
+			expect(screen.getByText('C')).toBeInTheDocument();
+		});
+	});
+
+	describe('search behavior (RIGHT position)', () => {
+		it('filters legend items based on search query (case-insensitive)', async () => {
+			const user = userEvent.setup();
+			renderLegend(LegendPosition.RIGHT);
+
+			const searchInput = screen.getByTestId('legend-search-input');
+			await user.type(searchInput, 'A');
+
+			expect(screen.getByText('A')).toBeInTheDocument();
+			expect(screen.queryByText('B')).not.toBeInTheDocument();
+			expect(screen.queryByText('C')).not.toBeInTheDocument();
+		});
+
+		it('shows empty state when no legend items match the search query', async () => {
+			const user = userEvent.setup();
+			renderLegend(LegendPosition.RIGHT);
+
+			const searchInput = screen.getByTestId('legend-search-input');
+			await user.type(searchInput, 'network');
+
+			expect(
+				screen.getByText(/No series found matching "network"/i),
+			).toBeInTheDocument();
+			expect(screen.queryByTestId('virtuoso-grid')).not.toBeInTheDocument();
+		});
+
+		it('does not filter or show empty state when search query is empty or only whitespace', async () => {
+			const user = userEvent.setup();
+			renderLegend(LegendPosition.RIGHT);
+
+			const searchInput = screen.getByTestId('legend-search-input');
+			await user.type(searchInput, '   ');
+
+			expect(
+				screen.queryByText(/No series found matching/i),
+			).not.toBeInTheDocument();
+			expect(screen.getByText('A')).toBeInTheDocument();
+			expect(screen.getByText('B')).toBeInTheDocument();
+			expect(screen.getByText('C')).toBeInTheDocument();
+		});
+	});
+
+	describe('legend actions', () => {
+		it('calls onLegendClick when a legend item is clicked', async () => {
+			const user = userEvent.setup();
+			renderLegend(LegendPosition.RIGHT);
+
+			await user.click(screen.getByText('A'));
+
+			expect(onLegendClick).toHaveBeenCalledTimes(1);
+		});
+
+		it('calls mouseMove when the mouse moves over a legend item', async () => {
+			const user = userEvent.setup();
+			renderLegend(LegendPosition.RIGHT);
+
+			const legendItem = document.querySelector(
+				'[data-legend-item-id="0"]',
+			) as HTMLElement;
+
+			await user.hover(legendItem);
+
+			expect(onLegendMouseMove).toHaveBeenCalledTimes(1);
+		});
+
+		it('calls onLegendMouseLeave when the mouse leaves the legend container', async () => {
+			const user = userEvent.setup();
+			renderLegend(LegendPosition.RIGHT);
+
+			const container = document.querySelector('.legend-container') as HTMLElement;
+
+			await user.hover(container);
+			await user.unhover(container);
+
+			expect(onLegendMouseLeave).toHaveBeenCalledTimes(1);
+		});
+	});
+});

frontend/src/lib/uPlotV2/components/types.ts

@@ -1,10 +1,11 @@
-import { ReactNode } from 'react';
+import { MouseEventHandler, ReactNode } from 'react';
 import { Timezone } from 'components/CustomTimePicker/timezoneUtils';
 import { PrecisionOption } from 'components/Graph/types';
 import uPlot from 'uplot';
 
 import { UPlotConfigBuilder } from '../config/UPlotConfigBuilder';
 import { LegendItem } from '../config/types';
+import { HeatmapSeries, HeatmapYAxis } from '../plugins/HeatmapPlugin/types';
 import { SyncTooltipFilterMode } from '../plugins/TooltipPlugin/types';
 
 /**
@@ -103,6 +104,21 @@ export interface BarTooltipProps extends BaseTooltipProps, TooltipRenderArgs {
 export interface HistogramTooltipProps
 	extends BaseTooltipProps, TooltipRenderArgs {}
 
+/** Not part of `TooltipProps`: it renders its own container, since none of its
+ *  states is the flat series list the shared `Tooltip` draws. */
+export interface HeatmapTooltipProps
+	extends BaseTooltipProps, TooltipRenderArgs {
+	yAxis: HeatmapYAxis;
+	/** Column width in seconds. */
+	step: number;
+	/** Needed to break a summed cell down by contribution. */
+	series: HeatmapSeries[];
+	/** Groups the legend has enabled; the cell sums exactly these. */
+	visibleGroups: string[];
+	/** Same colour the legend and the densest cells use. */
+	groupColor: string;
+}
+
 export type TooltipProps =
 	| TimeSeriesTooltipProps
 	| BarTooltipProps
@@ -115,39 +131,26 @@ export enum LegendPosition {
 export interface LegendConfig {
 	position: LegendPosition;
 }
-export enum LegendAction {
-	TOGGLE = 'toggle',
-	SHOW_ONLY = 'showOnly',
-	SHOW_ALL = 'showAll',
-	HOVER = 'hover',
-}
-
-/** Everything the legend can ask of its container, as one dispatch. */
-export type LegendActionPayload =
-	/** Row click / Space / Enter / marker click: hide or show that one series. */
-	| { type: LegendAction.TOGGLE; seriesIndex: number }
-	/** Show that series alone. */
-	| { type: LegendAction.SHOW_ONLY; seriesIndex: number }
-	/** Leave the narrowed selection and show every series. */
-	| { type: LegendAction.SHOW_ALL }
-	/** Row hover, for the chart-side highlight; null on leave. */
-	| { type: LegendAction.HOVER; seriesIndex: number | null };
-
-export type OnLegendAction = (payload: LegendActionPayload) => void;
-
 /**
  * Presentational legend props. Source-agnostic: it renders whatever `items`
  * it's given and delegates interaction to the container handlers, so it serves
- * both uPlot charts (via UPlotLegend) and non-uPlot charts (Pie).
+ * both uPlot charts (via UPlotLegend) and non-uPlot charts (Pie). The search
+ * box is intrinsic to the RIGHT position (derived from `position`, not a flag).
  */
 export interface LegendProps {
 	items: LegendItem[];
 	/** Legend placement; always supplied by the container. */
 	position: LegendPosition;
 	averageLegendWidth?: number;
-	/** Series index highlighted by the chart cursor. */
+	/** Series index to highlight (hovered/focused). */
 	focusedSeriesIndex: number | null;
-	onAction: OnLegendAction;
+	/**
+	 * Container-delegated handlers. Items carry `data-legend-item-id`, so the
+	 * handler reads the target's id rather than binding per item.
+	 */
+	onClick: MouseEventHandler<HTMLDivElement>;
+	onMouseMove: MouseEventHandler<HTMLDivElement>;
+	onMouseLeave: () => void;
 	/** Show the per-item copy button. Default true. */
 	showCopy?: boolean;
 }

frontend/src/lib/uPlotV2/config/UPlotAxisBuilder.ts

@@ -148,6 +148,7 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 			show = true,
 			side = 2, // bottom by default
 			space,
+			splits,
 			gap = 5, // default gap is 5
 		} = this.props;
 
@@ -179,6 +180,9 @@ export class UPlotAxisBuilder extends ConfigBuilder<AxisProps, Axis> {
 		if (values) {
 			axisConfig.values = values;
 		}
+		if (splits) {
+			axisConfig.splits = splits;
+		}
 		if (gap !== undefined) {
 			axisConfig.gap = gap;
 		}

frontend/src/lib/uPlotV2/config/UPlotScaleBuilder.ts

@@ -46,6 +46,13 @@ export class UPlotScaleBuilder extends ConfigBuilder<
 
 		// Special handling for time scales (X axis)
 		if (time) {
+			// An explicit range wins: the alignment below trims the tail of the window
+			// to whole minutes, which is right for point-based series but drops the
+			// final column of any chart whose marks span an interval.
+			if (range) {
+				return { [scaleKey]: { time: true, auto: false, range } };
+			}
+
 			let minTime = this.min ?? 0;
 			let maxTime = this.max ?? 0;
 

frontend/src/lib/uPlotV2/config/types.ts

@@ -78,6 +78,8 @@ export interface AxisProps {
 	};
 	/** Explicit tick formatter, replacing the scale's default (time / unit-formatted). */
 	values?: uPlot.Axis.Values;
+	/** Explicit axis splits, overriding the default tick calculation. */
+	splits?: uPlot.Axis.Splits;
 	/** Pixels between the ticks and their labels; also feeds the y axis width calculation. */
 	gap?: number;
 	/** Explicit axis thickness. Left unset, the y axis sizes itself to its widest label. */

frontend/src/lib/uPlotV2/constants.ts

@@ -6,11 +6,6 @@ export const DEFAULT_HOVER_PROXIMITY_VALUE = 30; // only snap if within 30px hor
 export const DEFAULT_FOCUS_PROXIMITY_VALUE = 1e6;
 export const STEP_INTERVAL_MULTIPLIER = 3; // multiply the width computed by STEP_INTERVAL_MULTIPLIER to get the hover prox value
 
-/** Opacity applied to the series that are NOT highlighted while a legend row is hovered. */
-export const LEGEND_HIGHLIGHT_DIM_ALPHA = 0.16;
-/** Stroke-width multiplier applied to the series highlighted from the legend. */
-export const LEGEND_HIGHLIGHT_WIDTH_RATIO = 1.6;
-
 export const DEFAULT_PLOT_CONFIG: Partial<Options> = {
 	focus: {
 		alpha: 0.3,

frontend/src/lib/uPlotV2/context/PlotContext.tsx

@@ -8,10 +8,6 @@ import {
 	useMemo,
 	useRef,
 } from 'react';
-import {
-	LEGEND_HIGHLIGHT_DIM_ALPHA,
-	LEGEND_HIGHLIGHT_WIDTH_RATIO,
-} from 'lib/uPlotV2/constants';
 import type { SeriesVisibilityItem } from 'lib/visualization/panels/types';
 import { updateSeriesVisibilityToLocalStorage } from 'lib/visualization/panels/utils/legendVisibilityUtils';
 import type uPlot from 'uplot';
@@ -24,26 +20,12 @@ export interface IPlotContext {
 	setPlotContextInitialState: (state: PlotContextInitialState) => void;
 	onToggleSeriesVisibility: (seriesIndex: number) => void;
 	onToggleSeriesOnOff: (seriesIndex: number) => void;
-	/** Show this series alone. */
-	onShowOnlySeries: (seriesIndex: number) => void;
-	/** Show every series again. */
-	onShowAllSeries: () => void;
 	onFocusSeries: (seriesIndex: number | null) => void;
-	/** Lift one series above the rest (dim + thicken) without changing visibility. */
-	onHighlightSeries: (seriesIndex: number | null) => void;
 	syncSeriesVisibilityToLocalStorage: () => void;
 }
 
 export const PlotContext = createContext<IPlotContext | null>(null);
 
-/** Data series (index 0 is the x-axis) currently drawn. */
-const countShownSeries = (plot: uPlot): number =>
-	plot.series.reduce(
-		(count, series, index) =>
-			index > 0 && series.show !== false ? count + 1 : count,
-		0,
-	);
-
 export const PlotContextProvider = ({
 	children,
 }: PropsWithChildren): JSX.Element => {
@@ -51,9 +33,6 @@ export const PlotContextProvider = ({
 	const activeSeriesIndex = useRef<number | undefined>(undefined);
 	const idRef = useRef<string | undefined>(undefined);
 	const shouldSavePreferencesRef = useRef<boolean>(false);
-	/** Pre-highlight stroke widths, captured on the first highlight so it can be undone. */
-	const baseSeriesWidthsRef = useRef<Map<number, number | undefined>>(new Map());
-	const highlightedSeriesIndexRef = useRef<number | null>(null);
 
 	const setPlotContextInitialState = useCallback(
 		({
@@ -64,8 +43,6 @@ export const PlotContextProvider = ({
 			uPlotInstanceRef.current = uPlotInstance;
 			idRef.current = id;
 			activeSeriesIndex.current = undefined;
-			baseSeriesWidthsRef.current = new Map();
-			highlightedSeriesIndexRef.current = null;
 			shouldSavePreferencesRef.current = !!shouldSaveSelectionPreference;
 		},
 		[],
@@ -87,54 +64,6 @@ export const PlotContextProvider = ({
 		updateSeriesVisibilityToLocalStorage(idRef.current, seriesVisibility);
 	}, []);
 
-	const onHighlightSeries = useCallback((seriesIndex: number | null): void => {
-		const plot = uPlotInstanceRef.current;
-		if (!plot) {
-			return;
-		}
-
-		highlightedSeriesIndexRef.current = seriesIndex;
-
-		plot.series.forEach((series, index) => {
-			if (index === 0) {
-				return;
-			}
-			if (!baseSeriesWidthsRef.current.has(index)) {
-				baseSeriesWidthsRef.current.set(index, series.width);
-			}
-			const baseWidth = baseSeriesWidthsRef.current.get(index);
-			const isHighlighted = index === seriesIndex;
-
-			/* eslint-disable no-param-reassign */
-			series.alpha =
-				seriesIndex === null || isHighlighted ? 1 : LEGEND_HIGHLIGHT_DIM_ALPHA;
-			series.width =
-				isHighlighted && baseWidth !== undefined
-					? baseWidth * LEGEND_HIGHLIGHT_WIDTH_RATIO
-					: baseWidth;
-			/* eslint-enable no-param-reassign */
-		});
-
-		// Only the stroke style changed, so the cached paths stay valid.
-		plot.redraw(false);
-	}, []);
-
-	/**
-	 * Leaving the dim on a hidden series leaves every other one faded, which
-	 * reads as an isolation rather than as one series being excluded.
-	 */
-	const clearHighlightIfHidden = useCallback((): void => {
-		const plot = uPlotInstanceRef.current;
-		const highlightedIndex = highlightedSeriesIndexRef.current;
-		if (!plot || highlightedIndex === null) {
-			return;
-		}
-
-		if (plot.series[highlightedIndex]?.show === false) {
-			onHighlightSeries(null);
-		}
-	}, [onHighlightSeries]);
-
 	const onToggleSeriesVisibility = useCallback(
 		(seriesIndex: number): void => {
 			const plot = uPlotInstanceRef.current;
@@ -174,61 +103,14 @@ export const PlotContextProvider = ({
 			if (!series) {
 				return;
 			}
-
-			// An empty chart is never worth reaching.
-			const isHiding = series.show !== false;
-			if (isHiding && countShownSeries(plot) <= 1) {
-				return;
-			}
-
 			plot.setSeries(seriesIndex, { show: !series.show });
 			if (idRef.current && shouldSavePreferencesRef.current) {
 				syncSeriesVisibilityToLocalStorage();
 			}
-
-			clearHighlightIfHidden();
 		},
-		[syncSeriesVisibilityToLocalStorage, clearHighlightIfHidden],
+		[syncSeriesVisibilityToLocalStorage],
 	);
 
-	/** Applies `resolveShow` to every data series in one batch, then persists. */
-	const setSeriesVisibility = useCallback(
-		(resolveShow: (seriesIndex: number) => boolean): void => {
-			const plot = uPlotInstanceRef.current;
-			if (!plot) {
-				return;
-			}
-
-			activeSeriesIndex.current = undefined;
-
-			plot.batch(() => {
-				plot.series.forEach((_, index) => {
-					if (index === 0) {
-						return;
-					}
-					plot.setSeries(index, { show: resolveShow(index) });
-				});
-				if (idRef.current && shouldSavePreferencesRef.current) {
-					syncSeriesVisibilityToLocalStorage();
-				}
-			});
-
-			clearHighlightIfHidden();
-		},
-		[syncSeriesVisibilityToLocalStorage, clearHighlightIfHidden],
-	);
-
-	const onShowOnlySeries = useCallback(
-		(seriesIndex: number): void => {
-			setSeriesVisibility((index) => index === seriesIndex);
-		},
-		[setSeriesVisibility],
-	);
-
-	const onShowAllSeries = useCallback((): void => {
-		setSeriesVisibility(() => true);
-	}, [setSeriesVisibility]);
-
 	const onFocusSeries = useCallback((seriesIndex: number | null): void => {
 		const plot = uPlotInstanceRef.current;
 		if (!plot) {
@@ -249,20 +131,14 @@ export const PlotContextProvider = ({
 			onToggleSeriesVisibility,
 			setPlotContextInitialState,
 			onToggleSeriesOnOff,
-			onShowOnlySeries,
-			onShowAllSeries,
 			onFocusSeries,
-			onHighlightSeries,
 			syncSeriesVisibilityToLocalStorage,
 		}),
 		[
 			onToggleSeriesVisibility,
 			setPlotContextInitialState,
 			onToggleSeriesOnOff,
-			onShowOnlySeries,
-			onShowAllSeries,
 			onFocusSeries,
-			onHighlightSeries,
 			syncSeriesVisibilityToLocalStorage,
 		],
 	);

frontend/src/lib/uPlotV2/context/__tests__/PlotContext.test.tsx

@@ -26,7 +26,6 @@ const createMockPlot = (series: MockSeries[] = []): uPlot =>
 		series,
 		batch: jest.fn((fn: () => void) => fn()),
 		setSeries: jest.fn(),
-		redraw: jest.fn(),
 	}) as unknown as uPlot;
 
 interface TestComponentProps {
@@ -45,10 +44,7 @@ const TestComponent = ({
 		syncSeriesVisibilityToLocalStorage,
 		onToggleSeriesVisibility,
 		onToggleSeriesOnOff,
-		onShowOnlySeries,
-		onShowAllSeries,
 		onFocusSeries,
-		onHighlightSeries,
 	} = usePlotContext();
 	const handleInit = (): void => {
 		if (!plot || !id || typeof shouldSaveSelectionPreference !== 'boolean') {
@@ -88,13 +84,6 @@ const TestComponent = ({
 			>
 				Toggle on/off 1
 			</button>
-			<button
-				type="button"
-				data-testid="toggle-on-off-2"
-				onClick={(): void => onToggleSeriesOnOff(2)}
-			>
-				Toggle on/off 2
-			</button>
 			<button
 				type="button"
 				data-testid="toggle-on-off-5"
@@ -109,34 +98,6 @@ const TestComponent = ({
 			>
 				Focus series
 			</button>
-			<button
-				type="button"
-				data-testid="show-only-1"
-				onClick={(): void => onShowOnlySeries(1)}
-			>
-				Show only 1
-			</button>
-			<button
-				type="button"
-				data-testid="show-all"
-				onClick={(): void => onShowAllSeries()}
-			>
-				Show all
-			</button>
-			<button
-				type="button"
-				data-testid="highlight-1"
-				onClick={(): void => onHighlightSeries(1)}
-			>
-				Highlight 1
-			</button>
-			<button
-				type="button"
-				data-testid="clear-highlight"
-				onClick={(): void => onHighlightSeries(null)}
-			>
-				Clear highlight
-			</button>
 		</div>
 	);
 };
@@ -312,7 +273,6 @@ describe('PlotContext', () => {
 			const series: MockSeries[] = [
 				{ label: 'x-axis', show: true },
 				{ label: 'CPU', show: true },
-				{ label: 'Memory', show: true },
 			];
 			const plot = createMockPlot(series);
 
@@ -364,7 +324,6 @@ describe('PlotContext', () => {
 			const series: MockSeries[] = [
 				{ label: 'x-axis', show: true },
 				{ label: 'CPU', show: true },
-				{ label: 'Memory', show: true },
 			];
 			const plot = createMockPlot(series);
 
@@ -384,48 +343,6 @@ describe('PlotContext', () => {
 			expect(plot.setSeries).toHaveBeenCalledWith(1, { show: false });
 			expect(mockUpdateSeriesVisibilityToLocalStorage).not.toHaveBeenCalled();
 		});
-
-		it('refuses to hide the last series showing', async () => {
-			const user = userEvent.setup();
-			const plot = createMockPlot([
-				{ label: 'x-axis', show: true },
-				{ label: 'CPU', show: true },
-				{ label: 'Memory', show: false },
-			]);
-
-			render(
-				<PlotContextProvider>
-					<TestComponent plot={plot} id="widget-123" shouldSaveSelectionPreference />
-				</PlotContextProvider>,
-			);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('toggle-on-off-1'));
-
-			// An empty chart is never a state worth reaching.
-			expect(plot.setSeries).not.toHaveBeenCalled();
-			expect(mockUpdateSeriesVisibilityToLocalStorage).not.toHaveBeenCalled();
-		});
-
-		it('still shows a hidden series when only one is left showing', async () => {
-			const user = userEvent.setup();
-			const plot = createMockPlot([
-				{ label: 'x-axis', show: true },
-				{ label: 'CPU', show: false },
-				{ label: 'Memory', show: true },
-			]);
-
-			render(
-				<PlotContextProvider>
-					<TestComponent plot={plot} id="widget-123" shouldSaveSelectionPreference />
-				</PlotContextProvider>,
-			);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('toggle-on-off-1'));
-
-			expect(plot.setSeries).toHaveBeenCalledWith(1, { show: true });
-		});
 	});
 
 	describe('onFocusSeries', () => {
@@ -464,193 +381,4 @@ describe('PlotContext', () => {
 			expect(plot.setSeries).toHaveBeenCalledWith(1, { focus: true }, false);
 		});
 	});
-	describe('onShowOnlySeries', () => {
-		const renderWithSeries = (
-			series: MockSeries[],
-		): { plot: uPlot; user: ReturnType<typeof userEvent.setup> } => {
-			const user = userEvent.setup();
-			const plot = createMockPlot(series);
-
-			render(
-				<PlotContextProvider>
-					<TestComponent plot={plot} id="widget-123" shouldSaveSelectionPreference />
-				</PlotContextProvider>,
-			);
-
-			return { plot, user };
-		};
-
-		it('hides every other series, leaving the x-axis alone', async () => {
-			const { plot, user } = renderWithSeries([
-				{ label: 'x-axis', show: true },
-				{ label: 'CPU', show: true },
-				{ label: 'Memory', show: true },
-			]);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('show-only-1'));
-
-			expect(plot.setSeries).toHaveBeenCalledWith(1, { show: true });
-			expect(plot.setSeries).toHaveBeenCalledWith(2, { show: false });
-			expect(plot.setSeries).not.toHaveBeenCalledWith(0, expect.anything());
-			expect(mockUpdateSeriesVisibilityToLocalStorage).toHaveBeenCalled();
-		});
-
-		it('keeps isolating the series that is already the only one shown', async () => {
-			const { plot, user } = renderWithSeries([
-				{ label: 'x-axis', show: true },
-				{ label: 'CPU', show: true },
-				{ label: 'Memory', show: false },
-			]);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('show-only-1'));
-
-			expect(plot.setSeries).toHaveBeenCalledWith(1, { show: true });
-			expect(plot.setSeries).toHaveBeenCalledWith(2, { show: false });
-		});
-	});
-
-	describe('onShowAllSeries', () => {
-		it('shows every hidden series again', async () => {
-			const user = userEvent.setup();
-			const plot = createMockPlot([
-				{ label: 'x-axis', show: true },
-				{ label: 'CPU', show: true },
-				{ label: 'Memory', show: false },
-			]);
-
-			render(
-				<PlotContextProvider>
-					<TestComponent plot={plot} id="widget-123" shouldSaveSelectionPreference />
-				</PlotContextProvider>,
-			);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('show-all'));
-
-			expect(plot.setSeries).toHaveBeenCalledWith(1, { show: true });
-			expect(plot.setSeries).toHaveBeenCalledWith(2, { show: true });
-			expect(plot.setSeries).not.toHaveBeenCalledWith(0, expect.anything());
-		});
-	});
-
-	describe('onHighlightSeries', () => {
-		const series = (): MockSeries[] => [
-			{ label: 'x-axis', show: true },
-			{ label: 'CPU', show: true, width: 2 },
-			{ label: 'Memory', show: true, width: 2 },
-		];
-
-		it('dims the other series and thickens the highlighted one', async () => {
-			const user = userEvent.setup();
-			const plot = createMockPlot(series());
-
-			render(
-				<PlotContextProvider>
-					<TestComponent plot={plot} id="widget-123" shouldSaveSelectionPreference />
-				</PlotContextProvider>,
-			);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('highlight-1'));
-
-			expect(plot.series[1].alpha).toBe(1);
-			expect(plot.series[1].width).toBe(3.2);
-			expect(plot.series[2].alpha).toBe(0.16);
-			expect(plot.series[2].width).toBe(2);
-			// Only the stroke changed, so the cached paths are reused.
-			expect(plot.redraw).toHaveBeenCalledWith(false);
-		});
-
-		it('restores every series when the highlight is cleared', async () => {
-			const user = userEvent.setup();
-			const plot = createMockPlot(series());
-
-			render(
-				<PlotContextProvider>
-					<TestComponent plot={plot} id="widget-123" shouldSaveSelectionPreference />
-				</PlotContextProvider>,
-			);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('highlight-1'));
-			await user.click(screen.getByTestId('clear-highlight'));
-
-			expect(plot.series[1].alpha).toBe(1);
-			expect(plot.series[1].width).toBe(2);
-			expect(plot.series[2].alpha).toBe(1);
-			expect(plot.series[2].width).toBe(2);
-		});
-
-		it('drops the dim when the highlighted series is hidden', async () => {
-			const user = userEvent.setup();
-			const plot = createMockPlot(series());
-			// The mock's setSeries doesn't mutate, so mirror what uPlot would do.
-			(plot.setSeries as jest.Mock).mockImplementation(
-				(index: number, opts: { show?: boolean }) => {
-					if (typeof opts.show === 'boolean') {
-						(plot.series[index] as MockSeries).show = opts.show;
-					}
-				},
-			);
-
-			render(
-				<PlotContextProvider>
-					<TestComponent plot={plot} id="widget-123" shouldSaveSelectionPreference />
-				</PlotContextProvider>,
-			);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('highlight-1'));
-			await user.click(screen.getByTestId('toggle-on-off-1'));
-
-			// Otherwise every remaining series stays faded and the panel reads as
-			// an isolation instead of one series being excluded.
-			expect(plot.series[2].alpha).toBe(1);
-			expect(plot.series[2].width).toBe(2);
-		});
-
-		it('keeps the dim when a different series is hidden', async () => {
-			const user = userEvent.setup();
-			const plot = createMockPlot(series());
-			(plot.setSeries as jest.Mock).mockImplementation(
-				(index: number, opts: { show?: boolean }) => {
-					if (typeof opts.show === 'boolean') {
-						(plot.series[index] as MockSeries).show = opts.show;
-					}
-				},
-			);
-
-			render(
-				<PlotContextProvider>
-					<TestComponent plot={plot} id="widget-123" shouldSaveSelectionPreference />
-				</PlotContextProvider>,
-			);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('highlight-1'));
-			await user.click(screen.getByTestId('toggle-on-off-2'));
-
-			expect(plot.series[1].alpha).toBe(1);
-			expect(plot.series[2].alpha).toBe(0.16);
-		});
-
-		it('leaves visibility untouched', async () => {
-			const user = userEvent.setup();
-			const plot = createMockPlot(series());
-
-			render(
-				<PlotContextProvider>
-					<TestComponent plot={plot} id="widget-123" shouldSaveSelectionPreference />
-				</PlotContextProvider>,
-			);
-
-			await user.click(screen.getByTestId('init'));
-			await user.click(screen.getByTestId('highlight-1'));
-
-			expect(plot.setSeries).not.toHaveBeenCalled();
-			expect(mockUpdateSeriesVisibilityToLocalStorage).not.toHaveBeenCalled();
-		});
-	});
 });

frontend/src/lib/uPlotV2/hooks/__tests__/useLegendActions.test.ts

@@ -1,5 +1,4 @@
 import { renderHook } from '@testing-library/react';
-import { LegendAction } from 'lib/uPlotV2/components/types';
 import { usePlotContext } from 'lib/uPlotV2/context/PlotContext';
 import { useLegendActions } from 'lib/uPlotV2/hooks/useLegendActions';
 
@@ -12,12 +11,10 @@ const mockUsePlotContext = usePlotContext as jest.MockedFunction<
 describe('useLegendActions', () => {
 	let onToggleSeriesVisibility: jest.Mock;
 	let onToggleSeriesOnOff: jest.Mock;
-	let onShowOnlySeries: jest.Mock;
-	let onShowAllSeries: jest.Mock;
-	let onFocusSeries: jest.Mock;
-	let onHighlightSeries: jest.Mock;
+	let onFocusSeriesPlot: jest.Mock;
 	let setPlotContextInitialState: jest.Mock;
 	let syncSeriesVisibilityToLocalStorage: jest.Mock;
+	let setFocusedSeriesIndexMock: jest.Mock;
 	let cancelAnimationFrameSpy: jest.SpyInstance<void, [handle: number]>;
 
 	beforeAll(() => {
@@ -40,20 +37,15 @@ describe('useLegendActions', () => {
 	beforeEach(() => {
 		onToggleSeriesVisibility = jest.fn();
 		onToggleSeriesOnOff = jest.fn();
-		onShowOnlySeries = jest.fn();
-		onShowAllSeries = jest.fn();
-		onFocusSeries = jest.fn();
-		onHighlightSeries = jest.fn();
+		onFocusSeriesPlot = jest.fn();
 		setPlotContextInitialState = jest.fn();
 		syncSeriesVisibilityToLocalStorage = jest.fn();
+		setFocusedSeriesIndexMock = jest.fn();
 
 		mockUsePlotContext.mockReturnValue({
 			onToggleSeriesVisibility,
 			onToggleSeriesOnOff,
-			onShowOnlySeries,
-			onShowAllSeries,
-			onFocusSeries,
-			onHighlightSeries,
+			onFocusSeries: onFocusSeriesPlot,
 			setPlotContextInitialState,
 			syncSeriesVisibilityToLocalStorage,
 		});
@@ -61,65 +53,149 @@ describe('useLegendActions', () => {
 		cancelAnimationFrameSpy.mockClear();
 	});
 
-	describe('visibility actions', () => {
-		it('toggles a single series on row click', () => {
-			const { result } = renderHook(() => useLegendActions());
+	const createMouseEvent = (options: {
+		legendItemId?: number;
+		isMarker?: boolean;
+	}): any => {
+		const { legendItemId, isMarker = false } = options;
 
-			result.current({ type: LegendAction.TOGGLE, seriesIndex: 2 });
+		return {
+			target: {
+				dataset: {
+					...(isMarker ? { isLegendMarker: 'true' } : {}),
+				},
+				closest: jest.fn(() =>
+					legendItemId !== undefined
+						? { dataset: { legendItemId: String(legendItemId) } }
+						: null,
+				),
+			},
+		};
+	};
 
-			expect(onToggleSeriesOnOff).toHaveBeenCalledWith(2);
-			// The row must never isolate — that is what "Only" is for.
+	describe('onLegendClick', () => {
+		it('toggles series visibility when clicking on legend label', async () => {
+			const { result } = renderHook(() =>
+				useLegendActions({
+					setFocusedSeriesIndex: setFocusedSeriesIndexMock,
+					focusedSeriesIndex: null,
+				}),
+			);
+
+			result.current.onLegendClick(createMouseEvent({ legendItemId: 0 }));
+
+			expect(onToggleSeriesVisibility).toHaveBeenCalledTimes(1);
+			expect(onToggleSeriesVisibility).toHaveBeenCalledWith(0);
+			expect(onToggleSeriesOnOff).not.toHaveBeenCalled();
+		});
+
+		it('toggles series on/off when clicking on marker', async () => {
+			const { result } = renderHook(() =>
+				useLegendActions({
+					setFocusedSeriesIndex: setFocusedSeriesIndexMock,
+					focusedSeriesIndex: null,
+				}),
+			);
+
+			result.current.onLegendClick(
+				createMouseEvent({ legendItemId: 0, isMarker: true }),
+			);
+
+			expect(onToggleSeriesOnOff).toHaveBeenCalledTimes(1);
+			expect(onToggleSeriesOnOff).toHaveBeenCalledWith(0);
 			expect(onToggleSeriesVisibility).not.toHaveBeenCalled();
 		});
 
-		it('forwards the Only and All actions to the plot', () => {
-			const { result } = renderHook(() => useLegendActions());
+		it('does nothing when click target is not inside a legend item', async () => {
+			const { result } = renderHook(() =>
+				useLegendActions({
+					setFocusedSeriesIndex: setFocusedSeriesIndexMock,
+					focusedSeriesIndex: null,
+				}),
+			);
 
-			result.current({ type: LegendAction.SHOW_ONLY, seriesIndex: 1 });
-			result.current({ type: LegendAction.SHOW_ALL });
+			result.current.onLegendClick(createMouseEvent({}));
 
-			expect(onShowOnlySeries).toHaveBeenCalledWith(1);
-			expect(onShowAllSeries).toHaveBeenCalled();
+			expect(onToggleSeriesOnOff).not.toHaveBeenCalled();
+			expect(onToggleSeriesVisibility).not.toHaveBeenCalled();
 		});
 	});
 
-	describe('hover highlight', () => {
-		it('highlights the hovered series', () => {
-			const { result } = renderHook(() => useLegendActions());
+	describe('onFocusSeries', () => {
+		it('schedules focus update and calls plot focus handler via mouse move', async () => {
+			const { result } = renderHook(() =>
+				useLegendActions({
+					setFocusedSeriesIndex: setFocusedSeriesIndexMock,
+					focusedSeriesIndex: null,
+				}),
+			);
 
-			result.current({ type: LegendAction.HOVER, seriesIndex: 2 });
+			result.current.onLegendMouseMove(createMouseEvent({ legendItemId: 0 }));
 
-			expect(onHighlightSeries).toHaveBeenCalledWith(2);
+			expect(setFocusedSeriesIndexMock).toHaveBeenCalledWith(0);
+			expect(onFocusSeriesPlot).toHaveBeenCalledWith(0);
 		});
 
-		it('clears the highlight on leave', () => {
-			const { result } = renderHook(() => useLegendActions());
+		it('cancels previous animation frame before scheduling new one on subsequent mouse moves', async () => {
+			const { result } = renderHook(() =>
+				useLegendActions({
+					setFocusedSeriesIndex: setFocusedSeriesIndexMock,
+					focusedSeriesIndex: null,
+				}),
+			);
 
-			result.current({ type: LegendAction.HOVER, seriesIndex: null });
+			result.current.onLegendMouseMove(createMouseEvent({ legendItemId: 0 }));
+			result.current.onLegendMouseMove(createMouseEvent({ legendItemId: 1 }));
 
-			expect(onHighlightSeries).toHaveBeenCalledWith(null);
-		});
-
-		it('coalesces rapid hovers into one frame', () => {
-			const { result } = renderHook(() => useLegendActions());
-
-			result.current({ type: LegendAction.HOVER, seriesIndex: 1 });
-			result.current({ type: LegendAction.HOVER, seriesIndex: 2 });
-
-			// Each new hover cancels the frame the previous one queued.
 			expect(cancelAnimationFrameSpy).toHaveBeenCalled();
 		});
+	});
 
-		it('cancels a pending highlight frame on unmount', () => {
-			jest
-				.spyOn(global, 'requestAnimationFrame')
-				.mockImplementation((): number => 7);
+	describe('onLegendMouseMove', () => {
+		it('focuses new series when hovering over different legend item', async () => {
+			const { result } = renderHook(() =>
+				useLegendActions({
+					setFocusedSeriesIndex: setFocusedSeriesIndexMock,
+					focusedSeriesIndex: 0,
+				}),
+			);
 
-			const { result, unmount } = renderHook(() => useLegendActions());
-			result.current({ type: LegendAction.HOVER, seriesIndex: 1 });
-			unmount();
+			result.current.onLegendMouseMove(createMouseEvent({ legendItemId: 1 }));
 
-			expect(cancelAnimationFrameSpy).toHaveBeenCalledWith(7);
+			expect(setFocusedSeriesIndexMock).toHaveBeenCalledWith(1);
+			expect(onFocusSeriesPlot).toHaveBeenCalledWith(1);
+		});
+
+		it('does nothing when hovering over already focused series', async () => {
+			const { result } = renderHook(() =>
+				useLegendActions({
+					setFocusedSeriesIndex: setFocusedSeriesIndexMock,
+					focusedSeriesIndex: 1,
+				}),
+			);
+
+			result.current.onLegendMouseMove(createMouseEvent({ legendItemId: 1 }));
+
+			expect(setFocusedSeriesIndexMock).not.toHaveBeenCalled();
+			expect(onFocusSeriesPlot).not.toHaveBeenCalled();
+		});
+	});
+
+	describe('onLegendMouseLeave', () => {
+		it('cancels pending animation frame and clears focus state', async () => {
+			const { result } = renderHook(() =>
+				useLegendActions({
+					setFocusedSeriesIndex: setFocusedSeriesIndexMock,
+					focusedSeriesIndex: null,
+				}),
+			);
+
+			result.current.onLegendMouseMove(createMouseEvent({ legendItemId: 0 }));
+			result.current.onLegendMouseLeave();
+
+			expect(cancelAnimationFrameSpy).toHaveBeenCalled();
+			expect(setFocusedSeriesIndexMock).toHaveBeenCalledWith(null);
+			expect(onFocusSeriesPlot).toHaveBeenCalledWith(null);
 		});
 	});
 });

frontend/src/lib/uPlotV2/hooks/useLegendActions.ts

@@ -1,66 +1,117 @@
-import { useCallback, useEffect, useRef } from 'react';
+import {
+	Dispatch,
+	SetStateAction,
+	useCallback,
+	useEffect,
+	useRef,
+} from 'react';
 import { usePlotContext } from 'lib/uPlotV2/context/PlotContext';
 
-import {
-	LegendAction,
-	LegendActionPayload,
-	OnLegendAction,
-} from '../components/types';
-
-/**
- * Legend interactions, bound to the plot through PlotContext. Hover is coalesced
- * to one chart redraw per frame.
- */
-export function useLegendActions(): OnLegendAction {
+export function useLegendActions({
+	setFocusedSeriesIndex,
+	focusedSeriesIndex,
+}: {
+	setFocusedSeriesIndex: Dispatch<SetStateAction<number | null>>;
+	focusedSeriesIndex: number | null;
+}): {
+	onLegendClick: (e: React.MouseEvent<HTMLDivElement>) => void;
+	onFocusSeries: (seriesIndex: number | null) => void;
+	onLegendMouseMove: (e: React.MouseEvent<HTMLDivElement>) => void;
+	onLegendMouseLeave: () => void;
+} {
 	const {
+		onFocusSeries: onFocusSeriesPlot,
 		onToggleSeriesOnOff,
-		onShowOnlySeries,
-		onShowAllSeries,
-		onHighlightSeries,
+		onToggleSeriesVisibility,
 	} = usePlotContext();
 
-	const rafIdRef = useRef<number | null>(null);
+	const rafId = useRef<number | null>(null); // requestAnimationFrame id
 
-	const cancelPendingHighlight = useCallback((): void => {
-		if (rafIdRef.current != null) {
-			cancelAnimationFrame(rafIdRef.current);
-			rafIdRef.current = null;
+	const getLegendItemIdFromEvent = useCallback(
+		(e: React.MouseEvent<HTMLDivElement>): string | undefined => {
+			const target = e.target as HTMLElement | null;
+			if (!target) {
+				return undefined;
+			}
+
+			const legendItemElement = target.closest<HTMLElement>(
+				'[data-legend-item-id]',
+			);
+
+			return legendItemElement?.dataset.legendItemId;
+		},
+		[],
+	);
+
+	const onLegendClick = useCallback(
+		(e: React.MouseEvent<HTMLDivElement>): void => {
+			const legendItemId = getLegendItemIdFromEvent(e);
+			if (!legendItemId) {
+				return;
+			}
+			const isLegendMarker = (e.target as HTMLElement).dataset.isLegendMarker;
+			const seriesIndex = Number(legendItemId);
+
+			if (isLegendMarker) {
+				onToggleSeriesOnOff(seriesIndex);
+				return;
+			}
+
+			onToggleSeriesVisibility(seriesIndex);
+		},
+		[onToggleSeriesVisibility, onToggleSeriesOnOff, getLegendItemIdFromEvent],
+	);
+
+	const onFocusSeries = useCallback(
+		(seriesIndex: number | null): void => {
+			if (rafId.current != null) {
+				cancelAnimationFrame(rafId.current);
+			}
+			rafId.current = requestAnimationFrame(() => {
+				setFocusedSeriesIndex(seriesIndex);
+				onFocusSeriesPlot(seriesIndex);
+			});
+		},
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+		[onFocusSeriesPlot],
+	);
+
+	const onLegendMouseMove = (e: React.MouseEvent<HTMLDivElement>): void => {
+		const legendItemId = getLegendItemIdFromEvent(e);
+		const seriesIndex = legendItemId ? Number(legendItemId) : null;
+		if (seriesIndex === focusedSeriesIndex) {
+			return;
 		}
-	}, []);
+		onFocusSeries(seriesIndex);
+	};
 
-	useEffect(() => cancelPendingHighlight, [cancelPendingHighlight]);
+	const onLegendMouseLeave = useCallback(
+		(): void => {
+			// Cancel any pending RAF from handleFocusSeries to prevent race condition
+			if (rafId.current != null) {
+				cancelAnimationFrame(rafId.current);
+				rafId.current = null;
+			}
+			setFocusedSeriesIndex(null);
+			onFocusSeries(null);
+		},
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+		[onFocusSeries],
+	);
 
-	return useCallback(
-		(payload: LegendActionPayload): void => {
-			switch (payload.type) {
-				case LegendAction.TOGGLE:
-					onToggleSeriesOnOff(payload.seriesIndex);
-					break;
-				case LegendAction.SHOW_ONLY:
-					onShowOnlySeries(payload.seriesIndex);
-					break;
-				case LegendAction.SHOW_ALL:
-					onShowAllSeries();
-					break;
-				case LegendAction.HOVER: {
-					const { seriesIndex } = payload;
-					cancelPendingHighlight();
-					rafIdRef.current = requestAnimationFrame(() => {
-						rafIdRef.current = null;
-						onHighlightSeries(seriesIndex);
-					});
-					break;
-				}
-				default:
-					break;
+	// Cleanup pending animation frames on unmount
+	useEffect(
+		() => (): void => {
+			if (rafId.current != null) {
+				cancelAnimationFrame(rafId.current);
 			}
 		},
-		[
-			cancelPendingHighlight,
-			onHighlightSeries,
-			onShowAllSeries,
-			onShowOnlySeries,
-			onToggleSeriesOnOff,
-		],
+		[],
 	);
+	return {
+		onLegendClick,
+		onFocusSeries,
+		onLegendMouseMove,
+		onLegendMouseLeave,
+	};
 }

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/colorScale.test.ts

@@ -0,0 +1,207 @@
+import {
+	clampColorSteps,
+	createHeatmapColorResolver,
+	DEFAULT_COLOR_STEPS,
+	DEFAULT_HEATMAP_COLORS,
+	getMaxCount,
+	MAX_COLOR_STEPS,
+	MIN_OPACITY_ALPHA,
+	normalizeCount,
+	resolveCountDomain,
+} from '../colorScale';
+import { HeatmapColorMode, HeatmapColorScale } from '../types';
+
+const SERIES_COLOR = '#4e74f8';
+
+describe('getMaxCount', () => {
+	it('ignores null cells', () => {
+		expect(
+			getMaxCount([
+				[1, null, 9],
+				[null, 4],
+			]),
+		).toBe(9);
+	});
+
+	it('returns 0 for an empty or all-null grid', () => {
+		expect(getMaxCount([])).toBe(0);
+		expect(getMaxCount([[null, null]])).toBe(0);
+	});
+
+	it('ignores non-finite counts', () => {
+		expect(getMaxCount([[3, Number.POSITIVE_INFINITY, Number.NaN]])).toBe(3);
+	});
+});
+
+describe('resolveCountDomain', () => {
+	it('floors at 0 on auto so a zero count sits at the bottom of the scale', () => {
+		expect(
+			resolveCountDomain({ minCount: null, maxCount: null }, [[5, 20]]),
+		).toStrictEqual({
+			min: 0,
+			max: 20,
+		});
+	});
+
+	it('honours explicit clamps', () => {
+		expect(
+			resolveCountDomain({ minCount: 10, maxCount: 100 }, [[5, 20]]),
+		).toStrictEqual({
+			min: 10,
+			max: 100,
+		});
+	});
+
+	it('collapses a max at or below min', () => {
+		expect(
+			resolveCountDomain({ minCount: 50, maxCount: 10 }, [[5]]),
+		).toStrictEqual({
+			min: 50,
+			max: 50,
+		});
+	});
+});
+
+describe('normalizeCount', () => {
+	const domain = { min: 0, max: 1000 };
+
+	it('spreads low counts on a log scale where a linear one washes them out', () => {
+		const log = (count: number): number =>
+			normalizeCount({ count, domain, scale: HeatmapColorScale.Log });
+
+		expect(log(10)).toBeCloseTo(1 / 3, 5);
+		expect(log(20)).toBeCloseTo(Math.log10(20) / 3, 5);
+		expect(
+			normalizeCount({ count: 10, domain, scale: HeatmapColorScale.Linear }),
+		).toBeCloseTo(0.01, 5);
+	});
+
+	it('puts 0 and 1 at the bottom of a log scale', () => {
+		expect(
+			normalizeCount({ count: 0, domain, scale: HeatmapColorScale.Log }),
+		).toBe(0);
+		expect(
+			normalizeCount({ count: 1, domain, scale: HeatmapColorScale.Log }),
+		).toBe(0);
+	});
+
+	it('reaches the top of the scale at max on every scale', () => {
+		[
+			HeatmapColorScale.Log,
+			HeatmapColorScale.Sqrt,
+			HeatmapColorScale.Linear,
+		].forEach((scale) => {
+			expect(normalizeCount({ count: 1000, domain, scale })).toBeCloseTo(1, 6);
+		});
+	});
+
+	it('takes the square root of the linear position on a sqrt scale', () => {
+		expect(
+			normalizeCount({
+				count: 250,
+				domain: { min: 0, max: 1000 },
+				scale: HeatmapColorScale.Sqrt,
+			}),
+		).toBeCloseTo(0.5, 6);
+	});
+
+	it('clamps counts outside the domain', () => {
+		const scale = HeatmapColorScale.Linear;
+		expect(normalizeCount({ count: -5, domain, scale })).toBe(0);
+		expect(normalizeCount({ count: 5000, domain, scale })).toBe(1);
+	});
+
+	it('returns the bottom of the scale when min equals max', () => {
+		expect(
+			normalizeCount({
+				count: 7,
+				domain: { min: 7, max: 7 },
+				scale: HeatmapColorScale.Log,
+			}),
+		).toBe(0);
+	});
+
+	it('handles a log domain whose min and max share a decade floor', () => {
+		expect(
+			normalizeCount({
+				count: 1,
+				domain: { min: 0, max: 1 },
+				scale: HeatmapColorScale.Log,
+			}),
+		).toBe(0);
+	});
+});
+
+describe('clampColorSteps', () => {
+	it('clamps to the supported range', () => {
+		expect(clampColorSteps(1)).toBe(2);
+		expect(clampColorSteps(500)).toBe(MAX_COLOR_STEPS);
+		expect(clampColorSteps(32)).toBe(32);
+	});
+
+	it('falls back to the default for a non-finite value', () => {
+		expect(clampColorSteps(Number.NaN)).toBe(DEFAULT_COLOR_STEPS);
+	});
+});
+
+describe('createHeatmapColorResolver', () => {
+	const build = (
+		overrides: Partial<typeof DEFAULT_HEATMAP_COLORS> = {},
+		isDarkMode = true,
+	): ReturnType<typeof createHeatmapColorResolver> =>
+		createHeatmapColorResolver({
+			options: { ...DEFAULT_HEATMAP_COLORS, ...overrides },
+			domain: { min: 0, max: 1000 },
+			isDarkMode,
+			seriesColor: SERIES_COLOR,
+		});
+
+	it('leaves null cells uncoloured so they can be hatched', () => {
+		const resolver = build();
+
+		expect(resolver.colorFor(null)).toBeNull();
+		expect(resolver.positionOf(null)).toBeNull();
+	});
+
+	it('gives a zero count the bottom colour, not the null treatment', () => {
+		const resolver = build();
+
+		expect(resolver.colorFor(0)).toBe(resolver.ramp[0]);
+	});
+
+	it('emits one ramp entry per step', () => {
+		expect(build({ steps: 8 }).ramp).toHaveLength(8);
+	});
+
+	it('maps the max count to the top of the ramp', () => {
+		const resolver = build({ steps: 8 });
+
+		expect(resolver.colorFor(1000)).toBe(resolver.ramp[7]);
+	});
+
+	it('picks different stops per theme so low counts stay near the surface', () => {
+		expect(build({}, true).ramp[0]).not.toBe(build({}, false).ramp[0]);
+	});
+
+	it('varies alpha in opacity mode, never below the visibility floor', () => {
+		const resolver = build({ mode: HeatmapColorMode.Opacity, steps: 4 });
+
+		expect(resolver.ramp[0]).toBe(`rgba(78, 116, 248, ${MIN_OPACITY_ALPHA})`);
+		// `color` drops the alpha channel from the string once it reaches 1.
+		expect(resolver.ramp[3]).toBe('rgb(78, 116, 248)');
+	});
+
+	it('prefers an explicit opacity fill over the series colour', () => {
+		const resolver = build({
+			mode: HeatmapColorMode.Opacity,
+			fill: '#e5484d',
+			steps: 2,
+		});
+
+		expect(resolver.ramp[1]).toBe('rgb(229, 72, 77)');
+	});
+
+	it('reports the domain it applied', () => {
+		expect(build().domain).toStrictEqual({ min: 0, max: 1000 });
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/geometry.test.ts

@@ -0,0 +1,356 @@
+import {
+	canUseLogAxis,
+	decimateAxisSplits,
+	formatRowLabel,
+	resolveColumnIndex,
+	resolveHeatmapYAxis,
+	resolveRowIndex,
+} from '../geometry';
+import { HeatmapAxisScale } from '../types';
+
+const BOUNDS = [128, 256, 1024, 4096];
+
+describe('canUseLogAxis', () => {
+	it('accepts strictly positive bounds', () => {
+		expect(canUseLogAxis(BOUNDS)).toBe(true);
+	});
+
+	it('rejects a zero or negative bound', () => {
+		expect(canUseLogAxis([0, 128])).toBe(false);
+		expect(canUseLogAxis([-1, 128])).toBe(false);
+	});
+
+	it('rejects empty bounds', () => {
+		expect(canUseLogAxis([])).toBe(false);
+	});
+});
+
+describe('resolveHeatmapYAxis', () => {
+	it('turns N bounds into N+1 rows with underflow and overflow at the ends', () => {
+		const { rows } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+
+		expect(rows).toHaveLength(BOUNDS.length + 1);
+		expect(rows[0]).toMatchObject({
+			upper: 128,
+			isUnderflow: true,
+			isOverflow: false,
+		});
+		expect(rows[1]).toMatchObject({ lower: 128, upper: 256 });
+		expect(rows[4]).toMatchObject({
+			lower: 4096,
+			isOverflow: true,
+			isUnderflow: false,
+		});
+	});
+
+	it('exposes one edge per row boundary, ascending', () => {
+		const { rows, edges } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+
+		expect(edges).toHaveLength(rows.length + 1);
+		expect([...edges].sort((a, b) => a - b)).toStrictEqual(edges);
+	});
+
+	it('places bounds in log space so row heights are log-proportional', () => {
+		const { splits, min, max } = resolveHeatmapYAxis(
+			BOUNDS,
+			HeatmapAxisScale.Log,
+		);
+
+		expect(splits).toStrictEqual(BOUNDS.map((bound) => Math.log10(bound)));
+		// Outer edges extend by the geometric mean ratio, (4096/128)^(1/3) = 3.174…
+		expect(10 ** min).toBeCloseTo(128 / (4096 / 128) ** (1 / 3), 6);
+		expect(10 ** max).toBeCloseTo(4096 * (4096 / 128) ** (1 / 3), 6);
+	});
+
+	it('keeps bounds in value space on a linear axis', () => {
+		const { splits, min } = resolveHeatmapYAxis(
+			[10, 20, 30],
+			HeatmapAxisScale.Linear,
+		);
+
+		expect(splits).toStrictEqual([10, 20, 30]);
+		// Mean gap is 10, and the underflow edge never crosses zero.
+		expect(min).toBe(0);
+	});
+
+	it('sorts and de-duplicates bounds', () => {
+		const { rows, splits } = resolveHeatmapYAxis(
+			[256, 128, 256, Number.NaN],
+			HeatmapAxisScale.Log,
+		);
+
+		expect(splits).toStrictEqual([Math.log10(128), Math.log10(256)]);
+		expect(rows).toHaveLength(3);
+	});
+
+	it('gives a single bound an underflow and an overflow row', () => {
+		const { rows, edges } = resolveHeatmapYAxis([100], HeatmapAxisScale.Log);
+
+		expect(rows).toHaveLength(2);
+		expect(rows[0].isUnderflow).toBe(true);
+		expect(rows[1].isOverflow).toBe(true);
+		expect(edges).toHaveLength(3);
+	});
+
+	it('degrades to an empty axis with no bounds', () => {
+		expect(resolveHeatmapYAxis([], HeatmapAxisScale.Log).rows).toStrictEqual([]);
+	});
+
+	it('puts the overflow label on the row"s upper edge, clear of the last boundary', () => {
+		const { overflowSplit, edges } = resolveHeatmapYAxis(
+			BOUNDS,
+			HeatmapAxisScale.Log,
+		);
+
+		// A full row above the last boundary tick, so the two labels cannot collide.
+		expect(overflowSplit).toBe(edges[edges.length - 1]);
+	});
+});
+
+describe('resolveRowIndex', () => {
+	const { edges } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Linear);
+
+	it('finds the row containing a value', () => {
+		expect(resolveRowIndex(edges, 200)).toBe(1);
+		expect(resolveRowIndex(edges, 2000)).toBe(3);
+	});
+
+	it('assigns a boundary to the row it opens', () => {
+		expect(resolveRowIndex(edges, 256)).toBe(2);
+	});
+
+	it('returns the last row on the top edge', () => {
+		expect(resolveRowIndex(edges, edges[edges.length - 1])).toBe(
+			edges.length - 2,
+		);
+	});
+
+	it('returns null outside the grid', () => {
+		expect(resolveRowIndex(edges, edges[0] - 1)).toBeNull();
+		expect(resolveRowIndex(edges, edges[edges.length - 1] + 1)).toBeNull();
+	});
+
+	it('returns null without at least one row', () => {
+		expect(resolveRowIndex([5], 5)).toBeNull();
+	});
+});
+
+describe('resolveColumnIndex', () => {
+	const timestamps = [100, 160, 220, 280];
+	const step = 60;
+
+	it('resolves by containment, not proximity', () => {
+		// 155 is nearer to 160, but the observations at 155 belong to column 0.
+		expect(resolveColumnIndex(timestamps, 155, step)).toBe(0);
+		expect(resolveColumnIndex(timestamps, 160, step)).toBe(1);
+	});
+
+	it('includes the column start and excludes its end', () => {
+		expect(resolveColumnIndex(timestamps, 100, step)).toBe(0);
+		expect(resolveColumnIndex(timestamps, 159.9, step)).toBe(0);
+	});
+
+	it('covers the trailing column using the step, not the next timestamp', () => {
+		expect(resolveColumnIndex(timestamps, 330, step)).toBe(3);
+		expect(resolveColumnIndex(timestamps, 340, step)).toBeNull();
+	});
+
+	it('returns null before the first column', () => {
+		expect(resolveColumnIndex(timestamps, 99, step)).toBeNull();
+	});
+
+	it('returns null with no columns', () => {
+		expect(resolveColumnIndex([], 100, step)).toBeNull();
+	});
+
+	it('leaves the last column open when the step is unknown', () => {
+		expect(resolveColumnIndex(timestamps, 10_000, 0)).toBe(3);
+	});
+});
+
+describe('formatRowLabel', () => {
+	const format = (value: number): string => `${value}ms`;
+	const { rows } = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Log);
+
+	it('labels the underflow row by its only real bound', () => {
+		expect(formatRowLabel(rows[0], format)).toBe('≤ 128ms');
+	});
+
+	it('labels the overflow row by its only real bound', () => {
+		expect(formatRowLabel(rows[rows.length - 1], format)).toBe('> 4096ms');
+	});
+
+	it('labels an interior row as a range', () => {
+		expect(formatRowLabel(rows[1], format)).toBe('128ms – 256ms');
+	});
+});
+
+describe('decimateAxisSplits', () => {
+	const splits = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+	const domain = { min: 0, max: 10 };
+
+	it('keeps every tick when they all fit', () => {
+		expect(
+			decimateAxisSplits({ ...domain, splits, plotHeight: 400, minGapPx: 18 }),
+		).toStrictEqual(splits);
+	});
+
+	it('thins to whatever fits at the available height', () => {
+		// 11 ticks over 100px is 10px apart; an 18px floor keeps every other one.
+		expect(
+			decimateAxisSplits({ ...domain, splits, plotHeight: 100, minGapPx: 18 }),
+		).toStrictEqual([0, 2, 4, 6, 8, 10]);
+	});
+
+	it('always keeps the topmost tick, so the overflow edge survives thinning', () => {
+		const thinned = decimateAxisSplits({
+			...domain,
+			splits,
+			plotHeight: 40,
+			minGapPx: 18,
+		});
+
+		expect(thinned[thinned.length - 1]).toBe(10);
+	});
+
+	it('returns ascending positions', () => {
+		const thinned = decimateAxisSplits({
+			...domain,
+			splits,
+			plotHeight: 60,
+			minGapPx: 18,
+		});
+
+		expect([...thinned].sort((a, b) => a - b)).toStrictEqual(thinned);
+	});
+
+	it('thins by pixel distance, not index, so uneven rows are handled', () => {
+		// Three boundaries bunched at the bottom of a wide linear domain: only the
+		// first and the far-away last are far enough apart to both get labels.
+		expect(
+			decimateAxisSplits({
+				splits: [1, 2, 3, 1000],
+				min: 0,
+				max: 1000,
+				plotHeight: 200,
+				minGapPx: 18,
+			}),
+		).toStrictEqual([3, 1000]);
+	});
+
+	it('leaves the tick set alone when it cannot measure', () => {
+		expect(
+			decimateAxisSplits({ ...domain, splits, plotHeight: 0, minGapPx: 18 }),
+		).toStrictEqual(splits);
+		expect(
+			decimateAxisSplits({
+				splits,
+				min: 5,
+				max: 5,
+				plotHeight: 400,
+				minGapPx: 18,
+			}),
+		).toStrictEqual(splits);
+	});
+});
+
+describe('resolveHeatmapYAxis — symmetric log', () => {
+	// The OTel SDK default explicit bucket boundaries, which start at zero.
+	const OTEL = [
+		0, 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000,
+	];
+	// Clock skew in ms — a logs/traces field that straddles zero.
+	const SKEW = [-1000, -100, -10, -1, 0, 1, 10, 100, 1000];
+
+	const PLOT_HEIGHT = 250;
+
+	/** Row heights in axis units, which map linearly to pixels. */
+	function rowHeights(bounds: number[]): number[] {
+		const { edges } = resolveHeatmapYAxis(bounds, HeatmapAxisScale.Log);
+		return edges.slice(1).map((edge, index) => edge - edges[index]);
+	}
+
+	/** Shortest row, in pixels, for a plot of `PLOT_HEIGHT`. */
+	function shortestRowPx(bounds: number[], scale: HeatmapAxisScale): number {
+		const { edges } = resolveHeatmapYAxis(bounds, scale);
+		const span = edges[edges.length - 1] - edges[0];
+		const heights = edges
+			.slice(1)
+			.map((edge, index) => ((edge - edges[index]) / span) * PLOT_HEIGHT);
+		return Math.min(...heights);
+	}
+
+	it('keeps a zero boundary on a log axis instead of giving up to linear', () => {
+		const { splits } = resolveHeatmapYAxis([0, 5, 10], HeatmapAxisScale.Log);
+
+		// A linear fallback would leave the boundaries untransformed.
+		expect(splits).not.toStrictEqual([0, 5, 10]);
+	});
+
+	it('gives every row a usable height for the OTel default boundaries', () => {
+		// Linear squeezes the 0–100ms buckets — where the data is — under a pixel.
+		expect(shortestRowPx(OTEL, HeatmapAxisScale.Linear)).toBeLessThan(1);
+		expect(shortestRowPx(OTEL, HeatmapAxisScale.Log)).toBeGreaterThan(4);
+	});
+
+	it('gives the zero-crossing row a full decade, since it cannot be compressed', () => {
+		const heights = rowHeights(OTEL);
+		const { rows } = resolveHeatmapYAxis(OTEL, HeatmapAxisScale.Log);
+		const nearZero = rows.findIndex((row) => row.lower === 0 && row.upper === 5);
+
+		// One axis unit — the same space a decade gets above the threshold.
+		expect(heights[nearZero]).toBeCloseTo(1, 6);
+	});
+
+	it('places boundaries either side of zero symmetrically', () => {
+		const heights = rowHeights(SKEW);
+
+		expect(Math.max(...heights) - Math.min(...heights)).toBeCloseTo(0, 6);
+	});
+
+	it('keeps negative boundaries ascending', () => {
+		const { edges } = resolveHeatmapYAxis(SKEW, HeatmapAxisScale.Log);
+
+		expect([...edges].sort((a, b) => a - b)).toStrictEqual(edges);
+	});
+
+	it('round-trips a boundary back to its bucket value', () => {
+		const { splits, toBucketValue } = resolveHeatmapYAxis(
+			SKEW,
+			HeatmapAxisScale.Log,
+		);
+
+		expect(
+			splits.map((split) => Math.round(toBucketValue(split) * 1e6) / 1e6),
+		).toStrictEqual(SKEW);
+	});
+
+	it('derives the linear threshold from the smallest non-zero boundary', () => {
+		// Threshold 10 puts -10 at -1 and 0 at 0 in axis space.
+		const { edges, rows } = resolveHeatmapYAxis(
+			[-100, -10, 0, 10, 100],
+			HeatmapAxisScale.Log,
+		);
+		const crossing = rows.findIndex(
+			(row) => row.lower === -10 && row.upper === 0,
+		);
+
+		expect(edges[crossing]).toBeCloseTo(-1, 6);
+		expect(edges[crossing + 1]).toBeCloseTo(0, 6);
+	});
+
+	it('leaves an all-positive layout on a plain log axis', () => {
+		const { splits } = resolveHeatmapYAxis(
+			[128, 256, 1024],
+			HeatmapAxisScale.Log,
+		);
+
+		expect(splits).toStrictEqual([128, 256, 1024].map((b) => Math.log10(b)));
+	});
+
+	it('falls back to linear when every boundary is zero', () => {
+		const { splits } = resolveHeatmapYAxis([0], HeatmapAxisScale.Log);
+
+		expect(splits).toStrictEqual([0]);
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/grid.test.ts

@@ -0,0 +1,176 @@
+import { resolveHeatmapGrid } from '../grid';
+import { HeatmapSeries } from '../types';
+
+const BUCKETS = [10, 20];
+const STEP = 60;
+
+/** Two groups over two columns, each missing a value the other reports. */
+const TWO_GROUPS: HeatmapSeries[] = [
+	{
+		label: 'cart',
+		points: [
+			{ timestamp: 60, counts: [1, 2, 3] },
+			{ timestamp: 120, counts: [null, 5, 6] },
+		],
+	},
+	{
+		label: 'checkout',
+		points: [
+			{ timestamp: 60, counts: [10, 20, 30] },
+			{ timestamp: 120, counts: [40, null, 60] },
+		],
+	},
+];
+
+function resolve(
+	overrides: Partial<Parameters<typeof resolveHeatmapGrid>[0]> = {},
+): ReturnType<typeof resolveHeatmapGrid> {
+	return resolveHeatmapGrid({
+		buckets: BUCKETS,
+		step: STEP,
+		series: TWO_GROUPS,
+		...overrides,
+	});
+}
+
+describe('resolveHeatmapGrid', () => {
+	it('pivots per-timestamp count arrays into one row per bucket', () => {
+		const { counts } = resolve({ series: [TWO_GROUPS[0]] });
+
+		// 2 boundaries describe 3 rows; each row spans both columns.
+		expect(counts).toStrictEqual([
+			[1, null],
+			[2, 5],
+			[3, 6],
+		]);
+	});
+
+	it('carries the bounds and step through untouched', () => {
+		const { bounds, step } = resolve();
+
+		expect(bounds).toStrictEqual(BUCKETS);
+		expect(step).toBe(STEP);
+	});
+
+	it('sums every group for the combined view', () => {
+		const { counts } = resolve();
+
+		expect(counts[0]).toStrictEqual([11, 40]);
+		expect(counts[2]).toStrictEqual([33, 66]);
+	});
+
+	it('keeps one group"s count where the other has no data', () => {
+		const { counts } = resolve();
+
+		// cart is null at 120 in row 0 while checkout reports 40.
+		expect(counts[0][1]).toBe(40);
+		// checkout is null at 120 in row 1 while cart reports 5.
+		expect(counts[1][1]).toBe(5);
+	});
+
+	it('reports a cell as no-data only when every group is missing it', () => {
+		const { counts } = resolve({
+			buckets: [10],
+			series: [
+				{ label: 'a', points: [{ timestamp: 60, counts: [null, null] }] },
+				{ label: 'b', points: [{ timestamp: 60, counts: [null, null] }] },
+			],
+		});
+
+		expect(counts).toStrictEqual([[null], [null]]);
+	});
+
+	it('distinguishes a zero count from no data', () => {
+		const { counts } = resolve({
+			buckets: [10],
+			series: [{ label: 'a', points: [{ timestamp: 60, counts: [0, null] }] }],
+		});
+
+		expect(counts[0][0]).toBe(0);
+		expect(counts[1][0]).toBeNull();
+	});
+
+	it('sums only the groups the legend has enabled', () => {
+		const { counts } = resolve({ visibleGroups: ['cart'] });
+
+		expect(counts[0]).toStrictEqual([1, null]);
+		expect(counts[2]).toStrictEqual([3, 6]);
+	});
+
+	it('sums every group when the legend passes nothing', () => {
+		const { counts } = resolve({ visibleGroups: undefined });
+
+		expect(counts[0]).toStrictEqual([11, 40]);
+	});
+
+	it('ignores an enabled label that left the result', () => {
+		const { counts } = resolve({ visibleGroups: ['cart', 'gone'] });
+
+		expect(counts[0]).toStrictEqual([1, null]);
+	});
+
+	it('empties the grid when every group is excluded', () => {
+		const { timestamps, counts } = resolve({ visibleGroups: [] });
+
+		expect(timestamps).toStrictEqual([]);
+		expect(counts.every((row) => row.length === 0)).toBe(true);
+	});
+
+	it('unions timestamps when groups do not align', () => {
+		const { timestamps, counts } = resolve({
+			buckets: [10],
+			series: [
+				{ label: 'a', points: [{ timestamp: 60, counts: [1, 2] }] },
+				{ label: 'b', points: [{ timestamp: 180, counts: [3, 4] }] },
+			],
+		});
+
+		expect(timestamps).toStrictEqual([60, 180]);
+		expect(counts[0]).toStrictEqual([1, 3]);
+	});
+
+	it('sorts columns ascending regardless of response order', () => {
+		const { timestamps } = resolve({
+			buckets: [10],
+			series: [
+				{
+					label: 'a',
+					points: [
+						{ timestamp: 180, counts: [1, 2] },
+						{ timestamp: 60, counts: [3, 4] },
+					],
+				},
+			],
+		});
+
+		expect(timestamps).toStrictEqual([60, 180]);
+	});
+
+	it('pads rows the response left short', () => {
+		const { counts } = resolve({
+			buckets: [10, 20, 30],
+			series: [{ label: 'a', points: [{ timestamp: 60, counts: [1, 2] }] }],
+		});
+
+		expect(counts).toStrictEqual([[1], [2], [null], [null]]);
+	});
+
+	it('ignores counts beyond the bucket rows', () => {
+		const { counts } = resolve({
+			buckets: [10],
+			series: [{ label: 'a', points: [{ timestamp: 60, counts: [1, 2, 99] }] }],
+		});
+
+		expect(counts).toStrictEqual([[1], [2]]);
+	});
+
+	it('degrades to an empty grid with no buckets or no series', () => {
+		expect(resolve({ buckets: [] })).toStrictEqual({
+			bounds: [],
+			timestamps: [],
+			step: 0,
+			counts: [],
+		});
+		expect(resolve({ series: [] }).counts).toStrictEqual([]);
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/heatmapPlugin.test.ts

@@ -0,0 +1,289 @@
+import type uPlot from 'uplot';
+
+import { DEFAULT_HEATMAP_COLORS } from '../colorScale';
+import { resolveHeatmapYAxis } from '../geometry';
+import { createHeatmapHooks } from '../heatmapPlugin';
+import { HeatmapAxisScale, HeatmapCell } from '../types';
+
+const BOUNDS = [100, 1000];
+const Y_AXIS = resolveHeatmapYAxis(BOUNDS, HeatmapAxisScale.Linear);
+const TIMESTAMPS = [1000, 1060, 1120];
+const STEP = 60;
+const PLOT_WIDTH = 300;
+const PLOT_HEIGHT = 300;
+
+// Three rows for two bounds, three columns; row 1 column 1 is a data gap.
+const DATA = [
+	TIMESTAMPS,
+	[1, 2, 3],
+	[4, null, 6],
+	[7, 8, 9],
+] as unknown as uPlot.AlignedData;
+
+interface FakeContext {
+	fillRect: jest.Mock;
+	fills: string[];
+}
+
+interface FakePlot {
+	plot: uPlot;
+	context: FakeContext;
+	setSeries: jest.Mock;
+	over: HTMLDivElement;
+}
+
+function createFakePlot(cursor: { left: number; top: number }): FakePlot {
+	const over = document.createElement('div');
+	Object.defineProperty(over, 'clientWidth', { value: PLOT_WIDTH });
+	Object.defineProperty(over, 'clientHeight', { value: PLOT_HEIGHT });
+
+	const fills: string[] = [];
+	const fillRect = jest.fn();
+	const context = { fills, fillRect };
+	const setSeries = jest.fn();
+
+	const xSpan = TIMESTAMPS[TIMESTAMPS.length - 1] + STEP - TIMESTAMPS[0];
+	const ySpan = Y_AXIS.max - Y_AXIS.min;
+
+	const ctx = {
+		save: jest.fn(),
+		restore: jest.fn(),
+		beginPath: jest.fn(),
+		rect: jest.fn(),
+		clip: jest.fn(),
+		moveTo: jest.fn(),
+		lineTo: jest.fn(),
+		stroke: jest.fn(),
+		setLineDash: jest.fn(),
+		createPattern: jest.fn(() => null),
+		set fillStyle(value: string) {
+			fills.push(value);
+		},
+		fillRect: (...args: number[]): void => {
+			fillRect(...args);
+		},
+	};
+
+	const plot = {
+		data: DATA,
+		cursor,
+		over,
+		setSeries,
+		ctx,
+		bbox: { left: 0, top: 0, width: PLOT_WIDTH, height: PLOT_HEIGHT },
+		scales: { x: { min: TIMESTAMPS[0], max: TIMESTAMPS[2] + STEP } },
+		// x grows left to right; y is inverted, so the highest bucket is at the top.
+		valToPos: (value: number, scaleKey: string): number =>
+			scaleKey === 'x'
+				? ((value - TIMESTAMPS[0]) / xSpan) * PLOT_WIDTH
+				: PLOT_HEIGHT - ((value - Y_AXIS.min) / ySpan) * PLOT_HEIGHT,
+		posToVal: (pos: number, scaleKey: string): number =>
+			scaleKey === 'x'
+				? TIMESTAMPS[0] + (pos / PLOT_WIDTH) * xSpan
+				: Y_AXIS.min + ((PLOT_HEIGHT - pos) / PLOT_HEIGHT) * ySpan,
+	};
+
+	return { plot: plot as unknown as uPlot, context, setSeries, over };
+}
+
+function createHooks(
+	onHoverChange?: (cell: HeatmapCell | null) => void,
+	dimOnHover = true,
+): ReturnType<typeof createHeatmapHooks> {
+	return createHeatmapHooks({
+		yAxis: Y_AXIS,
+		step: STEP,
+		colors: DEFAULT_HEATMAP_COLORS,
+		isDarkMode: true,
+		seriesColor: '#4e74f8',
+		dimOnHover,
+		onHoverChange,
+	});
+}
+
+describe('heatmap renderer — lifecycle', () => {
+	it('mounts the hover overlay into the plot overlay and tears it down', () => {
+		const hooks = createHooks();
+		const { plot, over } = createFakePlot({ left: -10, top: -10 });
+
+		hooks.init(plot);
+		expect(
+			over.querySelector('[data-testid="heatmap-hover-overlay"]'),
+		).not.toBeNull();
+
+		hooks.destroy(plot);
+		expect(
+			over.querySelector('[data-testid="heatmap-hover-overlay"]'),
+		).toBeNull();
+	});
+});
+
+describe('heatmap renderer — draw', () => {
+	it('paints every cell of every visible column', () => {
+		const hooks = createHooks();
+		const { plot, context } = createFakePlot({ left: -10, top: -10 });
+
+		hooks.init(plot);
+		hooks.draw(plot);
+
+		// 3 rows x 3 columns, less the one null cell that has no hatch pattern
+		// available under jsdom.
+		expect(context.fillRect).toHaveBeenCalledTimes(8);
+	});
+
+	it('gives a zero count the bottom-of-scale fill rather than skipping it', () => {
+		const hooks = createHooks();
+		const zeroed = [TIMESTAMPS, [0, 0, 0], [0, 0, 0], [0, 0, 0]];
+		const { plot, context } = createFakePlot({ left: -10, top: -10 });
+		(plot as { data: unknown }).data = zeroed;
+
+		hooks.init(plot);
+		hooks.draw(plot);
+
+		expect(context.fillRect).toHaveBeenCalledTimes(9);
+		expect(new Set(context.fills).size).toBe(1);
+	});
+
+	it('skips columns outside the current x range', () => {
+		const hooks = createHooks();
+		const { plot, context } = createFakePlot({ left: -10, top: -10 });
+		(plot as { scales: unknown }).scales = {
+			x: { min: TIMESTAMPS[0], max: TIMESTAMPS[0] + STEP },
+		};
+
+		hooks.init(plot);
+		hooks.draw(plot);
+
+		// Only the first two columns overlap the range; the third starts past its end.
+		// 2 columns x 3 rows, less the null cell in column 1.
+		expect(context.fillRect).toHaveBeenCalledTimes(5);
+	});
+
+	it('draws nothing without columns', () => {
+		const hooks = createHooks();
+		const { plot, context } = createFakePlot({ left: -10, top: -10 });
+		(plot as { data: unknown }).data = [[]];
+
+		hooks.init(plot);
+		hooks.draw(plot);
+
+		expect(context.fillRect).not.toHaveBeenCalled();
+	});
+});
+
+describe('heatmap renderer — hover', () => {
+	it('focuses the hovered row and reports the cell under the cursor', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		// Left third of the plot is column 0; the top third is the overflow row.
+		const { plot, setSeries } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenCalledWith({ row: 2, column: 0, count: 7 });
+		expect(setSeries).toHaveBeenCalledWith(3, { focus: true });
+	});
+
+	it('reports a data gap as a null count instead of zero', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		const { plot } = createFakePlot({
+			left: PLOT_WIDTH / 2,
+			top: PLOT_HEIGHT / 2,
+		});
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenCalledWith({
+			row: 1,
+			column: 1,
+			count: null,
+		});
+	});
+
+	it('does not re-report the same cell', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		const { plot } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenCalledTimes(1);
+	});
+
+	it('shows the overlay over the hovered cell and dims around it', () => {
+		const hooks = createHooks(undefined, true);
+		const { plot, over } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+
+		const overlay = over.querySelector<HTMLDivElement>(
+			'[data-testid="heatmap-hover-overlay"]',
+		);
+		expect(overlay?.style.display).toBe('block');
+		// Column 0 spans the left third of a 300px plot.
+		expect(overlay?.lastElementChild).toHaveStyle({
+			left: '0px',
+			width: '100px',
+		});
+	});
+
+	it('collapses the dim rects when dimming is off', () => {
+		const hooks = createHooks(undefined, false);
+		const { plot, over } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+
+		const overlay = over.querySelector<HTMLDivElement>(
+			'[data-testid="heatmap-hover-overlay"]',
+		);
+		expect(overlay?.firstElementChild).toHaveStyle({
+			width: '0px',
+			height: '0px',
+		});
+	});
+
+	it('releases focus and hides the overlay when the cursor leaves', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		const { plot, over, setSeries } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+		(plot as { cursor: { left: number; top: number } }).cursor = {
+			left: -10,
+			top: -10,
+		};
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenLastCalledWith(null);
+		expect(setSeries).toHaveBeenLastCalledWith(null, { focus: true });
+		expect(
+			over.querySelector<HTMLDivElement>('[data-testid="heatmap-hover-overlay"]')
+				?.style.display,
+		).toBe('none');
+	});
+
+	it('clears the hover when the cursor is inside the plot but past the last column', () => {
+		const onHoverChange = jest.fn();
+		const hooks = createHooks(onHoverChange);
+		const { plot } = createFakePlot({ left: 10, top: 10 });
+
+		hooks.init(plot);
+		hooks.setCursor(plot);
+		(plot as { data: unknown }).data = [[], [], [], []];
+		(plot as { cursor: { left: number; top: number } }).cursor = {
+			left: 10,
+			top: 10,
+		};
+		hooks.setCursor(plot);
+
+		expect(onHoverChange).toHaveBeenLastCalledWith(null);
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/__tests__/palettes.test.ts

@@ -0,0 +1,75 @@
+import { getPaletteStops } from '../palettes';
+import { HeatmapColorPalette } from '../types';
+
+const ALL_PALETTES = Object.values(HeatmapColorPalette);
+
+/** Perceived brightness, good enough to tell a ramp's ends apart. */
+function luminance(hex: string): number {
+	const value = parseInt(hex.slice(1), 16);
+	// eslint-disable-next-line no-bitwise
+	const [r, g, b] = [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+	return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+describe('getPaletteStops', () => {
+	it.each(ALL_PALETTES)('%s is a full ramp of valid colours', (palette) => {
+		const stops = getPaletteStops(palette, true);
+
+		expect(stops).toHaveLength(9);
+		stops.forEach((stop) => expect(stop).toMatch(/^#[0-9a-f]{6}$/));
+	});
+
+	it.each(ALL_PALETTES)(
+		'%s climbs from dark to bright on a dark panel',
+		(palette) => {
+			const stops = getPaletteStops(palette, true);
+
+			// Low counts must sit near the surface, whichever direction the ramp is
+			// stored in — otherwise empty cells become the loudest thing on screen.
+			expect(luminance(stops[0])).toBeLessThan(luminance(stops[stops.length - 1]));
+		},
+	);
+
+	it.each(ALL_PALETTES)(
+		'%s falls from pale to saturated on a light panel',
+		(palette) => {
+			const stops = getPaletteStops(palette, false);
+
+			expect(luminance(stops[0])).toBeGreaterThan(
+				luminance(stops[stops.length - 1]),
+			);
+		},
+	);
+
+	it.each(ALL_PALETTES)('%s uses the same colours in both themes', (palette) => {
+		// Only the polarity flips; the palette itself is theme-independent.
+		expect([...getPaletteStops(palette, false)].reverse()).toStrictEqual(
+			getPaletteStops(palette, true),
+		);
+	});
+
+	it('never mutates the stored ramp when reversing it', () => {
+		const first = getPaletteStops(HeatmapColorPalette.Lava, false);
+		const second = getPaletteStops(HeatmapColorPalette.Lava, false);
+
+		expect(first).toStrictEqual(second);
+	});
+
+	it('falls back to the first ramp for an unknown palette', () => {
+		const unknown = 'nope' as HeatmapColorPalette;
+
+		expect(getPaletteStops(unknown, true)).toStrictEqual(
+			getPaletteStops(HeatmapColorPalette.Ice, true),
+		);
+	});
+
+	it('offers a neutral ramp for panels that already spend colour elsewhere', () => {
+		const stops = getPaletteStops(HeatmapColorPalette.Graphite, true);
+
+		// Every stop is a grey: red, green and blue channels stay equal.
+		stops.forEach((stop) => {
+			expect(stop.slice(1, 3)).toBe(stop.slice(3, 5));
+			expect(stop.slice(3, 5)).toBe(stop.slice(5, 7));
+		});
+	});
+});

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/colorScale.ts

@@ -0,0 +1,198 @@
+import { Color as DesignToken } from '@signozhq/design-tokens';
+import Color from 'color';
+
+import { getPaletteStops } from './palettes';
+import {
+	HeatmapColorMode,
+	HeatmapColorOptions,
+	HeatmapColorScale,
+	HeatmapColorPalette,
+} from './types';
+
+export const MIN_COLOR_STEPS = 2;
+export const MAX_COLOR_STEPS = 128;
+export const DEFAULT_COLOR_STEPS = 64;
+
+/** Without a floor, the lowest counts read as "no data". */
+export const MIN_OPACITY_ALPHA = 0.1;
+
+/** Used when neither an explicit fill nor a series colour is available. */
+export const DEFAULT_OPACITY_FILL = DesignToken.BG_ROBIN_500;
+
+export const DEFAULT_HEATMAP_COLORS: HeatmapColorOptions = {
+	mode: HeatmapColorMode.Palette,
+	scale: HeatmapColorScale.Log,
+	minCount: null,
+	maxCount: null,
+	palette: HeatmapColorPalette.Lava,
+	steps: DEFAULT_COLOR_STEPS,
+	fill: '',
+};
+
+export interface CountDomain {
+	min: number;
+	max: number;
+}
+
+/** Highest count, ignoring `null`. 0 for an empty grid. */
+export function getMaxCount(counts: Array<Array<number | null>>): number {
+	let max = 0;
+	for (const row of counts) {
+		for (const count of row) {
+			if (count !== null && Number.isFinite(count) && count > max) {
+				max = count;
+			}
+		}
+	}
+	return max;
+}
+
+/** Explicit clamps win; otherwise 0 to the grid's highest count. */
+export function resolveCountDomain(
+	options: Pick<HeatmapColorOptions, 'minCount' | 'maxCount'>,
+	counts: Array<Array<number | null>>,
+): CountDomain {
+	const min = options.minCount ?? 0;
+	const max = options.maxCount ?? getMaxCount(counts);
+	return max > min ? { min, max } : { min, max: min };
+}
+
+/** Position on the colour scale, 0..1. A degenerate domain collapses to 0 so an
+ *  all-zero grid renders at the bottom rather than disappearing. */
+export function normalizeCount({
+	count,
+	domain,
+	scale,
+}: {
+	count: number;
+	domain: CountDomain;
+	scale: HeatmapColorScale;
+}): number {
+	const { min, max } = domain;
+	if (!(max > min)) {
+		return 0;
+	}
+
+	const clamped = Math.min(Math.max(count, min), max);
+
+	if (scale === HeatmapColorScale.Log) {
+		// 0 and 1 both sit at the bottom; log of either is meaningless.
+		const logMin = Math.log10(Math.max(min, 1));
+		const logMax = Math.log10(Math.max(max, 1));
+		if (!(logMax > logMin)) {
+			return 0;
+		}
+		return (Math.log10(Math.max(clamped, 1)) - logMin) / (logMax - logMin);
+	}
+
+	const linear = (clamped - min) / (max - min);
+	return scale === HeatmapColorScale.Sqrt ? Math.sqrt(linear) : linear;
+}
+
+export function clampColorSteps(steps: number): number {
+	if (!Number.isFinite(steps)) {
+		return DEFAULT_COLOR_STEPS;
+	}
+	return Math.min(Math.max(Math.round(steps), MIN_COLOR_STEPS), MAX_COLOR_STEPS);
+}
+
+/** Colour at `t` (0..1) along a multi-stop ramp. */
+function sampleStops(stops: string[], t: number): string {
+	if (stops.length === 0) {
+		return 'transparent';
+	}
+	if (stops.length === 1) {
+		return stops[0];
+	}
+	const scaled = Math.min(Math.max(t, 0), 1) * (stops.length - 1);
+	const lower = Math.min(Math.floor(scaled), stops.length - 2);
+	return Color(stops[lower])
+		.mix(Color(stops[lower + 1]), scaled - lower)
+		.hex();
+}
+
+/**
+ * Colour the densest cells are drawn with — the palette's extreme, or the opacity
+ * fill at full strength. Depends only on the options, not on the data, so callers
+ * can read it before a grid exists.
+ */
+export function resolveExtremeColor({
+	options,
+	isDarkMode,
+	seriesColor,
+}: {
+	options: HeatmapColorOptions;
+	isDarkMode: boolean;
+	seriesColor: string;
+}): string {
+	if (options.mode === HeatmapColorMode.Opacity) {
+		return options.fill || seriesColor || DEFAULT_OPACITY_FILL;
+	}
+	const stops = getPaletteStops(options.palette, isDarkMode);
+	return stops[stops.length - 1] ?? DEFAULT_OPACITY_FILL;
+}
+
+export interface HeatmapColorResolver {
+	/** `null` for a `null` count, which must be hatched. */
+	colorFor: (count: number | null) => string | null;
+	/** 0..1, or `null` for a `null` count. */
+	positionOf: (count: number | null) => number | null;
+	/** Low to high. The colour bar renders exactly these. */
+	ramp: string[];
+	domain: CountDomain;
+}
+
+/** Palette mode walks a sequential ramp; opacity mode varies the alpha of one
+ *  fill, so the grid matches its group's legend swatch. */
+export function createHeatmapColorResolver({
+	options,
+	domain,
+	isDarkMode,
+	seriesColor,
+}: {
+	options: HeatmapColorOptions;
+	domain: CountDomain;
+	isDarkMode: boolean;
+	/** Opacity-mode fill when `options.fill` is empty. */
+	seriesColor: string;
+}): HeatmapColorResolver {
+	const steps = clampColorSteps(options.steps);
+	const positions = Array.from({ length: steps }, (_, index) =>
+		steps === 1 ? 0 : index / (steps - 1),
+	);
+
+	let ramp: string[];
+	if (options.mode === HeatmapColorMode.Opacity) {
+		const base = Color(options.fill || seriesColor || DEFAULT_OPACITY_FILL);
+		ramp = positions.map((t) =>
+			base
+				.alpha(MIN_OPACITY_ALPHA + t * (1 - MIN_OPACITY_ALPHA))
+				.rgb()
+				.string(),
+		);
+	} else {
+		const stops = getPaletteStops(options.palette, isDarkMode);
+		ramp = positions.map((t) => sampleStops(stops, t));
+	}
+
+	const positionOf = (count: number | null): number | null => {
+		if (count === null || !Number.isFinite(count)) {
+			return null;
+		}
+		return normalizeCount({ count, domain, scale: options.scale });
+	};
+
+	return {
+		positionOf,
+		colorFor: (count): string | null => {
+			const t = positionOf(count);
+			if (t === null) {
+				return null;
+			}
+			const index = Math.min(Math.floor(t * steps), steps - 1);
+			return ramp[index];
+		},
+		ramp,
+		domain,
+	};
+}

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/geometry.ts

@@ -0,0 +1,297 @@
+import { HeatmapAxisScale, HeatmapRow, HeatmapYAxis } from './types';
+
+/** Used when the ratio cannot be inferred, i.e. a single boundary. */
+const FALLBACK_LOG_RATIO = 2;
+
+const EMPTY_Y_AXIS: HeatmapYAxis = {
+	rows: [],
+	edges: [],
+	splits: [],
+	overflowSplit: null,
+	toBucketValue: (axisValue: number): number => axisValue,
+	min: 0,
+	max: 1,
+};
+
+/** Ascending, finite, de-duplicated boundaries. */
+function normalizeBounds(bounds: number[]): number[] {
+	const sorted = bounds
+		.filter((bound) => Number.isFinite(bound))
+		.sort((a, b) => a - b);
+	return sorted.filter(
+		(bound, index) => index === 0 || bound !== sorted[index - 1],
+	);
+}
+
+/** True when a plain log axis can place every boundary. */
+export function canUseLogAxis(bounds: number[]): boolean {
+	return bounds.length > 0 && bounds.every((bound) => bound > 0);
+}
+
+interface AxisTransform {
+	toAxisValue: (value: number) => number;
+	toBucketValue: (axisValue: number) => number;
+}
+
+const LINEAR_TRANSFORM: AxisTransform = {
+	toAxisValue: (value) => value,
+	toBucketValue: (axisValue) => axisValue,
+};
+
+const LOG_TRANSFORM: AxisTransform = {
+	toAxisValue: (value) => Math.log10(value),
+	toBucketValue: (axisValue) => 10 ** axisValue,
+};
+
+/**
+ * Where "near zero" starts, taken as the smallest non-zero boundary magnitude. The
+ * bucket layout already declares it, so it never needs to be configured.
+ */
+function resolveLinearThreshold(bounds: number[]): number {
+	let threshold = Number.POSITIVE_INFINITY;
+	for (const bound of bounds) {
+		const magnitude = Math.abs(bound);
+		if (magnitude > 0 && magnitude < threshold) {
+			threshold = magnitude;
+		}
+	}
+	return Number.isFinite(threshold) ? threshold : 1;
+}
+
+/**
+ * Symmetric log: linear within ±threshold, logarithmic beyond, mirrored across
+ * zero. Bucketing an arbitrary logs/traces field can straddle zero — clock skew,
+ * deltas, balances — which a plain log cannot place at all, and which a linear axis
+ * squeezes into sub-pixel rows exactly where the interesting data sits.
+ *
+ * The gradient kink at ±threshold is invisible here: the threshold *is* a boundary,
+ * so it lands on a row edge, and row edges are already discrete.
+ */
+function createSymlogTransform(threshold: number): AxisTransform {
+	return {
+		toAxisValue: (value) =>
+			Math.abs(value) <= threshold
+				? value / threshold
+				: Math.sign(value) * (1 + Math.log10(Math.abs(value) / threshold)),
+		toBucketValue: (axisValue) =>
+			Math.abs(axisValue) <= 1
+				? axisValue * threshold
+				: Math.sign(axisValue) * threshold * 10 ** (Math.abs(axisValue) - 1),
+	};
+}
+
+function resolveAxisTransform(
+	bounds: number[],
+	scale: HeatmapAxisScale,
+): AxisTransform {
+	if (scale !== HeatmapAxisScale.Log) {
+		return LINEAR_TRANSFORM;
+	}
+	if (canUseLogAxis(bounds)) {
+		return LOG_TRANSFORM;
+	}
+	// All-zero bounds have no magnitude to scale against.
+	if (!bounds.some((bound) => bound !== 0)) {
+		return LINEAR_TRANSFORM;
+	}
+	return createSymlogTransform(resolveLinearThreshold(bounds));
+}
+
+/**
+ * The open-ended rows still need a height, so each gets the grid's typical bucket
+ * width — the mean gap in axis space, which on a geometric layout is exactly one
+ * bucket ratio. Linear stays in value space so it can refuse to cross zero.
+ */
+function resolveOuterEdges(
+	bounds: number[],
+	transform: AxisTransform,
+	isLinear: boolean,
+): { lower: number; upper: number } {
+	const first = bounds[0];
+	const last = bounds[bounds.length - 1];
+
+	if (isLinear) {
+		const gap = bounds.length > 1 ? (last - first) / (bounds.length - 1) : 0;
+		const safeGap = gap > 0 ? gap : Math.abs(first) || 1;
+		// Never extend below zero unless the boundaries already do.
+		const lower = first > 0 ? Math.max(0, first - safeGap) : first - safeGap;
+		return { lower, upper: last + safeGap };
+	}
+
+	const axisFirst = transform.toAxisValue(first);
+	const axisLast = transform.toAxisValue(last);
+	const fallback = Math.log10(FALLBACK_LOG_RATIO);
+	const gap =
+		bounds.length > 1 ? (axisLast - axisFirst) / (bounds.length - 1) : fallback;
+	const safeGap = gap > 0 ? gap : fallback;
+
+	return {
+		lower: transform.toBucketValue(axisFirst - safeGap),
+		upper: transform.toBucketValue(axisLast + safeGap),
+	};
+}
+
+/** N boundaries produce N+1 rows: an underflow row below the first, and the
+ *  `+Inf` overflow row above the last. */
+export function resolveHeatmapYAxis(
+	bounds: number[],
+	scale: HeatmapAxisScale,
+): HeatmapYAxis {
+	const normalized = normalizeBounds(bounds);
+	if (normalized.length === 0) {
+		return EMPTY_Y_AXIS;
+	}
+
+	const transform = resolveAxisTransform(normalized, scale);
+	const isLinear = transform === LINEAR_TRANSFORM;
+	const { toAxisValue, toBucketValue } = transform;
+
+	const { lower, upper } = resolveOuterEdges(normalized, transform, isLinear);
+	const last = normalized[normalized.length - 1];
+
+	const rows: HeatmapRow[] = [
+		{ lower, upper: normalized[0], isUnderflow: true, isOverflow: false },
+	];
+	for (let index = 1; index < normalized.length; index += 1) {
+		rows.push({
+			lower: normalized[index - 1],
+			upper: normalized[index],
+			isUnderflow: false,
+			isOverflow: false,
+		});
+	}
+	rows.push({ lower: last, upper, isUnderflow: false, isOverflow: true });
+
+	const edges = [
+		toAxisValue(lower),
+		...normalized.map(toAxisValue),
+		toAxisValue(upper),
+	];
+
+	return {
+		rows,
+		edges,
+		splits: normalized.map(toAxisValue),
+		overflowSplit: toAxisValue(upper),
+		toBucketValue,
+		min: edges[0],
+		max: edges[edges.length - 1],
+	};
+}
+
+/** Row containing `axisValue`, or `null` when it falls outside the grid. */
+export function resolveRowIndex(
+	edges: number[],
+	axisValue: number,
+): number | null {
+	if (edges.length < 2) {
+		return null;
+	}
+	if (axisValue < edges[0] || axisValue > edges[edges.length - 1]) {
+		return null;
+	}
+
+	let low = 0;
+	let high = edges.length - 2;
+	while (low <= high) {
+		const mid = (low + high) >> 1;
+		if (axisValue < edges[mid]) {
+			high = mid - 1;
+		} else if (axisValue >= edges[mid + 1]) {
+			low = mid + 1;
+		} else {
+			return mid;
+		}
+	}
+	// Exactly on the top edge.
+	return edges.length - 2;
+}
+
+/**
+ * A containment test, not a nearest-timestamp lookup: uPlot's own `cursor.idx`
+ * snaps to the closest boundary and would report the next column as soon as the
+ * cursor passed a cell's midpoint.
+ */
+export function resolveColumnIndex(
+	timestamps: ArrayLike<number>,
+	xValue: number,
+	step: number,
+): number | null {
+	if (timestamps.length === 0) {
+		return null;
+	}
+
+	let low = 0;
+	let high = timestamps.length - 1;
+	let candidate = -1;
+	while (low <= high) {
+		const mid = (low + high) >> 1;
+		if (timestamps[mid] <= xValue) {
+			candidate = mid;
+			low = mid + 1;
+		} else {
+			high = mid - 1;
+		}
+	}
+
+	if (candidate < 0) {
+		return null;
+	}
+	const width = step > 0 ? step : Number.POSITIVE_INFINITY;
+	return xValue < timestamps[candidate] + width ? candidate : null;
+}
+
+/** The open-ended rows are labelled by their one real boundary; the synthetic
+ *  edge is a drawing device, not a value. */
+export function formatRowLabel(
+	row: HeatmapRow,
+	formatValue: (value: number) => string,
+): string {
+	if (row.isOverflow) {
+		return `> ${formatValue(row.lower)}`;
+	}
+	if (row.isUnderflow) {
+		return `≤ ${formatValue(row.upper)}`;
+	}
+	return `${formatValue(row.lower)} – ${formatValue(row.upper)}`;
+}
+
+/**
+ * Drops boundary ticks that would overlap. Filters by pixel distance rather than
+ * index, since linear rows are not the same height, and walks down from the top
+ * so the `∞` edge survives whatever else is dropped.
+ */
+export function decimateAxisSplits({
+	splits,
+	min,
+	max,
+	plotHeight,
+	minGapPx,
+}: {
+	/** Candidates in axis space, ascending. */
+	splits: number[];
+	min: number;
+	max: number;
+	/** Plotting area height, in CSS pixels. */
+	plotHeight: number;
+	minGapPx: number;
+}): number[] {
+	if (splits.length < 2 || plotHeight <= 0 || minGapPx <= 0 || !(max > min)) {
+		return splits;
+	}
+
+	const pixelsPerUnit = plotHeight / (max - min);
+	const kept: number[] = [];
+	let lastPosition = 0;
+
+	for (let index = splits.length - 1; index >= 0; index -= 1) {
+		// Axis values grow upward, pixel offsets downward.
+		const position = (max - splits[index]) * pixelsPerUnit;
+		if (kept.length === 0 || position - lastPosition >= minGapPx) {
+			kept.push(splits[index]);
+			lastPosition = position;
+		}
+	}
+
+	return kept.reverse();
+}

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/grid.ts

@@ -0,0 +1,99 @@
+import { HeatmapGrid, HeatmapSeries } from './types';
+
+const EMPTY_GRID: HeatmapGrid = {
+	bounds: [],
+	timestamps: [],
+	step: 0,
+	counts: [],
+};
+
+/**
+ * Highest single-cell count each group reaches. Read against the same domain the
+ * colour bar uses, this is where a group sits on that bar.
+ */
+export function resolveGroupPeaks(
+	series: HeatmapSeries[],
+): Map<string, number> {
+	const peaks = new Map<string, number>();
+	series.forEach((entry) => {
+		let peak = 0;
+		entry.points.forEach((point) =>
+			point.counts.forEach((count) => {
+				if (count !== null && count > peak) {
+					peak = count;
+				}
+			}),
+		);
+		peaks.set(entry.label, peak);
+	});
+	return peaks;
+}
+
+/** Groups the legend currently has enabled. `undefined` means all of them. */
+function resolveVisible(
+	series: HeatmapSeries[],
+	visibleGroups: string[] | undefined,
+): HeatmapSeries[] {
+	if (visibleGroups === undefined) {
+		return series;
+	}
+	const allowed = new Set(visibleGroups);
+	return series.filter((entry) => allowed.has(entry.label));
+}
+
+/**
+ * Pivots the response's column-major counts into the row-major grid the renderer
+ * draws, and sums the enabled groups — counts are additive, so the sum is exact and
+ * needs no extra request. A cell is `null` only when no group contributed to it.
+ */
+export function resolveHeatmapGrid({
+	buckets,
+	step,
+	series,
+	visibleGroups,
+}: {
+	buckets: number[];
+	/** Column width in seconds. */
+	step: number;
+	series: HeatmapSeries[];
+	/** Labels the legend has enabled. `undefined` sums every group. */
+	visibleGroups?: string[];
+}): HeatmapGrid {
+	if (buckets.length === 0 || series.length === 0) {
+		return EMPTY_GRID;
+	}
+
+	const selected = resolveVisible(series, visibleGroups);
+
+	// Groups are not guaranteed to share timestamps, so the columns are their union.
+	const timestampSet = new Set<number>();
+	selected.forEach((entry) => {
+		entry.points.forEach((point) => timestampSet.add(point.timestamp));
+	});
+	const timestamps = Array.from(timestampSet).sort((a, b) => a - b);
+	const columnOf = new Map(timestamps.map((value, index) => [value, index]));
+
+	// N boundaries describe N+1 rows: the underflow row and the `+Inf` overflow row.
+	const rowCount = buckets.length + 1;
+	const counts: Array<Array<number | null>> = Array.from(
+		{ length: rowCount },
+		() => new Array<number | null>(timestamps.length).fill(null),
+	);
+
+	selected.forEach((entry) => {
+		entry.points.forEach((point) => {
+			const column = columnOf.get(point.timestamp);
+			if (column === undefined) {
+				return;
+			}
+			point.counts.forEach((count, row) => {
+				if (row >= rowCount || count === null || count === undefined) {
+					return;
+				}
+				counts[row][column] = (counts[row][column] ?? 0) + count;
+			});
+		});
+	});
+
+	return { bounds: buckets, timestamps, step, counts };
+}

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/heatmapPlugin.ts

@@ -0,0 +1,170 @@
+import uPlot from 'uplot';
+
+import {
+	createHeatmapColorResolver,
+	HeatmapColorResolver,
+	resolveCountDomain,
+} from './colorScale';
+import { resolveColumnIndex, resolveRowIndex } from './geometry';
+import {
+	createHoverOverlay,
+	HeatmapHoverOverlay,
+	showHoverOverlay,
+} from './hoverOverlay';
+import { createHatchPattern, drawCells, drawOverflowBoundary } from './paint';
+import { HeatmapCell, HeatmapColorOptions, HeatmapYAxis } from './types';
+
+export interface HeatmapRenderOptions {
+	yAxis: HeatmapYAxis;
+	/** Column width in seconds. */
+	step: number;
+	colors: HeatmapColorOptions;
+	isDarkMode: boolean;
+	/** Opacity-mode fill when `colors.fill` is empty. */
+	seriesColor: string;
+	/** Default true. */
+	dimOnHover?: boolean;
+	/** `null` when the cursor leaves. */
+	onHoverChange?: (cell: HeatmapCell | null) => void;
+}
+
+/**
+ * Registered through `UPlotConfigBuilder.addHook`, not as a `uPlot.Plugin`: uPlot
+ * appends plugin hooks *after* the hook arrays, and `setCursor` must run before
+ * TooltipPlugin's so the focused row is resolved when the tooltip positions
+ * itself. As a plugin it trails a frame and the tooltip flashes at the origin.
+ */
+export interface HeatmapHooks {
+	init: (u: uPlot) => void;
+	draw: (u: uPlot) => void;
+	setCursor: (u: uPlot) => void;
+	destroy: (u: uPlot) => void;
+}
+
+export function createHeatmapHooks({
+	yAxis,
+	step,
+	colors,
+	isDarkMode,
+	seriesColor,
+	dimOnHover = true,
+	onHoverChange,
+}: HeatmapRenderOptions): HeatmapHooks {
+	let overlay: HeatmapHoverOverlay | null = null;
+	let hovered: HeatmapCell | null = null;
+	let hatchPattern: CanvasPattern | null = null;
+
+	// On auto, the domain comes from the data, but these hooks are captured once at
+	// config-build time. Resolving lazily keeps a refetch on uPlot's `setData` path
+	// rather than forcing a rebuild.
+	let cachedData: uPlot.AlignedData | null = null;
+	let cachedResolver: HeatmapColorResolver | null = null;
+
+	function getResolver(u: uPlot): HeatmapColorResolver {
+		if (cachedResolver && cachedData === u.data) {
+			return cachedResolver;
+		}
+		cachedResolver = createHeatmapColorResolver({
+			options: colors,
+			domain: resolveCountDomain(
+				colors,
+				u.data.slice(1) as Array<Array<number | null>>,
+			),
+			isDarkMode,
+			seriesColor,
+		});
+		cachedData = u.data;
+		return cachedResolver;
+	}
+
+	function clearHover(u: uPlot): void {
+		if (overlay) {
+			overlay.container.style.display = 'none';
+		}
+		if (hovered === null) {
+			return;
+		}
+		hovered = null;
+		u.setSeries(null, { focus: true });
+		onHoverChange?.(null);
+	}
+
+	return {
+		init: (u: uPlot): void => {
+			overlay = createHoverOverlay(isDarkMode);
+			u.over.appendChild(overlay.container);
+		},
+
+		draw: (u: uPlot): void => {
+			const timestamps = u.data[0] as ArrayLike<number> | undefined;
+			if (!timestamps?.length || yAxis.rows.length === 0) {
+				return;
+			}
+			const { ctx } = u;
+			hatchPattern ??= createHatchPattern(ctx, isDarkMode);
+
+			ctx.save();
+			ctx.beginPath();
+			ctx.rect(u.bbox.left, u.bbox.top, u.bbox.width, u.bbox.height);
+			ctx.clip();
+			drawCells({ u, yAxis, step, resolver: getResolver(u), hatchPattern });
+			ctx.restore();
+
+			drawOverflowBoundary({ u, yAxis, isDarkMode });
+		},
+
+		setCursor: (u: uPlot): void => {
+			const { left = -10, top = -10 } = u.cursor;
+			if (left < 0 || top < 0) {
+				clearHover(u);
+				return;
+			}
+
+			const column = resolveColumnIndex(
+				u.data[0] as ArrayLike<number>,
+				u.posToVal(left, 'x'),
+				step,
+			);
+			const row = resolveRowIndex(yAxis.edges, u.posToVal(top, 'y'));
+			if (column === null || row === null) {
+				clearHover(u);
+				return;
+			}
+			if (hovered?.row === row && hovered?.column === column) {
+				return;
+			}
+
+			hovered = {
+				row,
+				column,
+				count:
+					(u.data[row + 1] as Array<number | null> | undefined)?.[column] ?? null,
+			};
+			// Drives TooltipPlugin, which only shows a tooltip for a focused series.
+			// uPlot's own focus is disabled here: it picks the series nearest in value
+			// space, and a heatmap's value is a colour, not a y coordinate.
+			u.setSeries(row + 1, { focus: true });
+			if (overlay) {
+				showHoverOverlay({
+					overlay,
+					u,
+					yAxis,
+					step,
+					row,
+					column,
+					dim: dimOnHover,
+				});
+			}
+			onHoverChange?.(hovered);
+		},
+
+		destroy: (): void => {
+			overlay?.container.remove();
+			overlay = null;
+			hovered = null;
+			hatchPattern = null;
+			cachedData = null;
+			cachedResolver = null;
+		},
+	};
+}

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/hoverOverlay.ts

@@ -0,0 +1,118 @@
+import { Color } from '@signozhq/design-tokens';
+import uPlot from 'uplot';
+
+import { HeatmapYAxis } from './types';
+
+const HIGHLIGHT_BORDER_WIDTH = 1;
+/** ~55% alpha. */
+const DIM_ALPHA = '8C';
+
+export interface HeatmapHoverOverlay {
+	container: HTMLDivElement;
+	highlight: HTMLDivElement;
+	/** Four corner rects whose complement is the hovered row/column cross. */
+	dims: HTMLDivElement[];
+}
+
+function createOverlayElement(): HTMLDivElement {
+	const element = document.createElement('div');
+	element.style.position = 'absolute';
+	element.style.pointerEvents = 'none';
+	return element;
+}
+
+function setRect(
+	element: HTMLDivElement,
+	left: number,
+	top: number,
+	width: number,
+	height: number,
+): void {
+	element.style.left = `${left}px`;
+	element.style.top = `${top}px`;
+	element.style.width = `${Math.max(0, width)}px`;
+	element.style.height = `${Math.max(0, height)}px`;
+}
+
+/** Kept out of the canvas so moving between cells repositions a few nodes
+ *  instead of repainting the grid. */
+export function createHoverOverlay(isDarkMode: boolean): HeatmapHoverOverlay {
+	const container = createOverlayElement();
+	container.style.inset = '0';
+	container.style.display = 'none';
+	container.setAttribute('data-testid', 'heatmap-hover-overlay');
+
+	const dimColor = `${
+		isDarkMode ? Color.BG_INK_500 : Color.BG_VANILLA_100
+	}${DIM_ALPHA}`;
+	const dims = Array.from({ length: 4 }, () => {
+		const dim = createOverlayElement();
+		dim.style.background = dimColor;
+		container.appendChild(dim);
+		return dim;
+	});
+
+	const highlight = createOverlayElement();
+	highlight.style.border = `${HIGHLIGHT_BORDER_WIDTH}px solid ${
+		isDarkMode ? Color.BG_VANILLA_100 : Color.BG_INK_300
+	}`;
+	highlight.style.boxSizing = 'border-box';
+	container.appendChild(highlight);
+
+	return { container, highlight, dims };
+}
+
+/** Positions the highlight, and the four corner rects so only the hovered row
+ *  and column stay at full contrast. */
+export function showHoverOverlay({
+	overlay,
+	u,
+	yAxis,
+	step,
+	row,
+	column,
+	dim,
+}: {
+	overlay: HeatmapHoverOverlay;
+	u: uPlot;
+	yAxis: HeatmapYAxis;
+	step: number;
+	row: number;
+	column: number;
+	dim: boolean;
+}): void {
+	const timestamps = u.data[0] as ArrayLike<number>;
+	const width = u.over.clientWidth;
+	const height = u.over.clientHeight;
+
+	const cellLeft = u.valToPos(timestamps[column], 'x');
+	const cellRight = u.valToPos(timestamps[column] + step, 'x');
+	const cellTop = u.valToPos(yAxis.edges[row + 1], 'y');
+	const cellBottom = u.valToPos(yAxis.edges[row], 'y');
+
+	setRect(
+		overlay.highlight,
+		cellLeft,
+		cellTop,
+		cellRight - cellLeft,
+		cellBottom - cellTop,
+	);
+
+	const [topLeft, topRight, bottomLeft, bottomRight] = overlay.dims;
+	if (dim) {
+		setRect(topLeft, 0, 0, cellLeft, cellTop);
+		setRect(topRight, cellRight, 0, width - cellRight, cellTop);
+		setRect(bottomLeft, 0, cellBottom, cellLeft, height - cellBottom);
+		setRect(
+			bottomRight,
+			cellRight,
+			cellBottom,
+			width - cellRight,
+			height - cellBottom,
+		);
+	} else {
+		overlay.dims.forEach((element) => setRect(element, 0, 0, 0, 0));
+	}
+
+	overlay.container.style.display = 'block';
+}

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/paint.ts

@@ -0,0 +1,128 @@
+import { Color } from '@signozhq/design-tokens';
+import uPlot from 'uplot';
+
+import { HeatmapColorResolver } from './colorScale';
+import { HeatmapYAxis } from './types';
+
+/** Cells at least this wide/tall keep a hairline separator. */
+const MIN_CELL_SIZE_FOR_GAP = 4;
+const HATCH_TILE_SIZE = 6;
+const OVERFLOW_DASH: [number, number] = [4, 3];
+
+/** Hatch for `null` cells: a gap must never share the bottom-of-scale fill, or a
+ *  scrape outage reads as a quiet period. */
+export function createHatchPattern(
+	ctx: CanvasRenderingContext2D,
+	isDarkMode: boolean,
+): CanvasPattern | null {
+	const pxRatio = uPlot.pxRatio;
+	const size = Math.max(2, Math.round(HATCH_TILE_SIZE * pxRatio));
+	const tile = document.createElement('canvas');
+	tile.width = size;
+	tile.height = size;
+
+	const tileCtx = tile.getContext('2d');
+	if (!tileCtx) {
+		return null;
+	}
+	tileCtx.strokeStyle = isDarkMode
+		? `${Color.BG_VANILLA_400}59`
+		: `${Color.BG_INK_300}40`;
+	tileCtx.lineWidth = Math.max(1, pxRatio);
+	tileCtx.beginPath();
+	// Three strokes keep the pattern continuous across tile seams.
+	tileCtx.moveTo(0, size);
+	tileCtx.lineTo(size, 0);
+	tileCtx.moveTo(-size / 2, size / 2);
+	tileCtx.lineTo(size / 2, -size / 2);
+	tileCtx.moveTo(size / 2, size * 1.5);
+	tileCtx.lineTo(size * 1.5, size / 2);
+	tileCtx.stroke();
+
+	return ctx.createPattern(tile, 'repeat');
+}
+
+/** One canvas pass. Offscreen columns are skipped rather than clipped. */
+// eslint-disable-next-line sonarjs/cognitive-complexity
+export function drawCells({
+	u,
+	yAxis,
+	step,
+	resolver,
+	hatchPattern,
+}: {
+	u: uPlot;
+	yAxis: HeatmapYAxis;
+	step: number;
+	resolver: HeatmapColorResolver;
+	hatchPattern: CanvasPattern | null;
+}): void {
+	const { ctx } = u;
+	const timestamps = u.data[0] as ArrayLike<number>;
+	const { rows, edges } = yAxis;
+	const pxRatio = uPlot.pxRatio;
+
+	const xMin = u.scales.x.min ?? timestamps[0];
+	const xMax = u.scales.x.max ?? timestamps[timestamps.length - 1] + step;
+	const rowEdgePositions = edges.map((edge) => u.valToPos(edge, 'y', true));
+
+	for (let column = 0; column < timestamps.length; column += 1) {
+		const columnStart = timestamps[column];
+		const columnEnd = columnStart + step;
+		if (columnEnd < xMin || columnStart > xMax) {
+			continue;
+		}
+
+		const left = u.valToPos(columnStart, 'x', true);
+		const rawWidth = u.valToPos(columnEnd, 'x', true) - left;
+		const gapX = rawWidth > MIN_CELL_SIZE_FOR_GAP * pxRatio ? pxRatio : 0;
+		const width = Math.max(1, rawWidth - gapX);
+
+		for (let row = 0; row < rows.length; row += 1) {
+			const top = rowEdgePositions[row + 1];
+			const rawHeight = rowEdgePositions[row] - top;
+			const gapY = rawHeight > MIN_CELL_SIZE_FOR_GAP * pxRatio ? pxRatio : 0;
+
+			const count = (u.data[row + 1] as Array<number | null> | undefined)?.[
+				column
+			];
+			const fill = resolver.colorFor(count ?? null);
+
+			if (fill === null && hatchPattern === null) {
+				continue;
+			}
+			ctx.fillStyle = fill ?? (hatchPattern as CanvasPattern);
+			ctx.fillRect(left, top, width, Math.max(1, rawHeight - gapY));
+		}
+	}
+}
+
+/** The `+Inf` row is unbounded, so its height is a drawing convenience and
+ *  should not be compared with the real buckets. */
+export function drawOverflowBoundary({
+	u,
+	yAxis,
+	isDarkMode,
+}: {
+	u: uPlot;
+	yAxis: HeatmapYAxis;
+	isDarkMode: boolean;
+}): void {
+	const overflowIndex = yAxis.rows.length - 1;
+	if (overflowIndex < 1 || !yAxis.rows[overflowIndex].isOverflow) {
+		return;
+	}
+
+	const { ctx } = u;
+	const y = Math.round(u.valToPos(yAxis.edges[overflowIndex], 'y', true));
+
+	ctx.save();
+	ctx.setLineDash(OVERFLOW_DASH);
+	ctx.lineWidth = Math.max(1, uPlot.pxRatio);
+	ctx.strokeStyle = isDarkMode ? Color.BG_VANILLA_400 : Color.BG_INK_300;
+	ctx.beginPath();
+	ctx.moveTo(u.bbox.left, y);
+	ctx.lineTo(u.bbox.left + u.bbox.width, y);
+	ctx.stroke();
+	ctx.restore();
+}

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/palettes.ts

@@ -0,0 +1,167 @@
+import { HeatmapColorPalette } from './types';
+
+interface PaletteDefinition {
+	/** Evenly spaced, one end of the ramp to the other. */
+	stops: string[];
+	/** `true` when `stops[0]` is the dark end. */
+	darkFirst: boolean;
+}
+
+/**
+ * Stop values come from the long-established public palette families —
+ * ColorBrewer for the hue ramps, matplotlib's perceptual set for the rest.
+ */
+const PALETTES: Record<HeatmapColorPalette, PaletteDefinition> = {
+	[HeatmapColorPalette.Ice]: {
+		darkFirst: false,
+		stops: [
+			'#f7fbff',
+			'#deebf7',
+			'#c3dbee',
+			'#9cc8e2',
+			'#6daed5',
+			'#4391c6',
+			'#2271b4',
+			'#0c5198',
+			'#08306b',
+		],
+	},
+	[HeatmapColorPalette.Moss]: {
+		darkFirst: false,
+		stops: [
+			'#f7fcf5',
+			'#e3f4de',
+			'#c6e8bf',
+			'#a0d89b',
+			'#73c378',
+			'#45aa5d',
+			'#228b45',
+			'#066b2d',
+			'#00441b',
+		],
+	},
+	[HeatmapColorPalette.Rust]: {
+		darkFirst: false,
+		stops: [
+			'#fff5f0',
+			'#feddcf',
+			'#fcbaa1',
+			'#fc9273',
+			'#f9694c',
+			'#eb3d2f',
+			'#cb1c1e',
+			'#a10e15',
+			'#67000d',
+		],
+	},
+	[HeatmapColorPalette.Graphite]: {
+		darkFirst: false,
+		stops: [
+			'#ffffff',
+			'#efefef',
+			'#d8d8d8',
+			'#bbbbbb',
+			'#979797',
+			'#737373',
+			'#505050',
+			'#262626',
+			'#000000',
+		],
+	},
+	[HeatmapColorPalette.Ember]: {
+		darkFirst: false,
+		stops: [
+			'#ffffcc',
+			'#ffeda0',
+			'#fed676',
+			'#feb250',
+			'#fd893c',
+			'#f8502b',
+			'#e11e20',
+			'#b90424',
+			'#800026',
+		],
+	},
+	[HeatmapColorPalette.Lagoon]: {
+		darkFirst: false,
+		stops: [
+			'#ffffd9',
+			'#eaf7b8',
+			'#c1e7b5',
+			'#81cebb',
+			'#45b4c2',
+			'#248fbd',
+			'#2260a9',
+			'#20378d',
+			'#081d58',
+		],
+	},
+	[HeatmapColorPalette.Orchid]: {
+		darkFirst: false,
+		stops: [
+			'#fff7f3',
+			'#fddfdc',
+			'#fcc3c3',
+			'#fa9cb4',
+			'#f369a3',
+			'#da3495',
+			'#ad0a81',
+			'#7b0176',
+			'#49006a',
+		],
+	},
+	[HeatmapColorPalette.Verdant]: {
+		darkFirst: true,
+		stops: [
+			'#440154',
+			'#472d7b',
+			'#3b528b',
+			'#2c728e',
+			'#21918c',
+			'#28ae80',
+			'#5ec962',
+			'#addc30',
+			'#fde725',
+		],
+	},
+	[HeatmapColorPalette.Lava]: {
+		darkFirst: true,
+		stops: [
+			'#000004',
+			'#1d1147',
+			'#51127c',
+			'#832681',
+			'#b73779',
+			'#e75263',
+			'#fc8961',
+			'#fec488',
+			'#fcfdbf',
+		],
+	},
+	[HeatmapColorPalette.Beacon]: {
+		darkFirst: true,
+		stops: [
+			'#002051',
+			'#11366c',
+			'#3c4d6e',
+			'#62646f',
+			'#7f7c75',
+			'#9a9478',
+			'#bbaf71',
+			'#e2cb5c',
+			'#fdea45',
+		],
+	},
+};
+
+/** Stops oriented low-count first for the active theme. At the wrong polarity,
+ *  empty cells become the loudest thing on screen. */
+export function getPaletteStops(
+	palette: HeatmapColorPalette,
+	isDarkMode: boolean,
+): string[] {
+	const definition = PALETTES[palette] ?? PALETTES[HeatmapColorPalette.Ice];
+	return definition.darkFirst === isDarkMode
+		? definition.stops
+		: [...definition.stops].reverse();
+}

frontend/src/lib/uPlotV2/plugins/HeatmapPlugin/types.ts

@@ -0,0 +1,113 @@
+export enum HeatmapColorScale {
+	Log = 'log',
+	Sqrt = 'sqrt',
+	Linear = 'linear',
+}
+
+export enum HeatmapColorMode {
+	Palette = 'palette',
+	Opacity = 'opacity',
+}
+
+/** Sequential ramps only: colour means "count", so a midpoint or hue cycle would
+ *  read as a threshold that does not exist. */
+export enum HeatmapColorPalette {
+	Ice = 'ice',
+	Moss = 'moss',
+	Rust = 'rust',
+	Graphite = 'graphite',
+	Ember = 'ember',
+	Lagoon = 'lagoon',
+	Orchid = 'orchid',
+	Verdant = 'verdant',
+	Lava = 'lava',
+	Beacon = 'beacon',
+}
+
+export interface HeatmapColorOptions {
+	mode: HeatmapColorMode;
+	scale: HeatmapColorScale;
+	/** `null` derives it, which is always 0 — a count of 0 belongs at the bottom. */
+	minCount: number | null;
+	/** `null` derives it from the grid's highest count. */
+	maxCount: number | null;
+	palette: HeatmapColorPalette;
+	/** Colour steps the ramp is quantised into, 2..128. Unrelated to `step`, the
+	 *  column width in seconds. */
+	steps: number;
+	/** Opacity mode. Empty falls back to the caller's series colour. */
+	fill: string;
+}
+
+/** Row-height distribution of the bucket axis. */
+export enum HeatmapAxisScale {
+	Log = 'log',
+	Linear = 'linear',
+}
+
+export interface HeatmapSeriesPoint {
+	/** Column start, in seconds. */
+	timestamp: number;
+	/** One per bucket row, lowest first. `null` is "no data", never `0`. */
+	counts: Array<number | null>;
+}
+
+export interface HeatmapSeriesLabel {
+	key: string;
+	value: string;
+}
+
+export interface HeatmapSeries {
+	/** Group label, as the legend names it. Empty when there is no grouping. */
+	label: string;
+	/** The pairs behind `label`, letting the tooltip name rows by value alone. */
+	labels?: HeatmapSeriesLabel[];
+	points: HeatmapSeriesPoint[];
+}
+
+/** Counts pivoted into rows and aligned to one column axis. Internal to the
+ *  chart, which resolves it from `buckets` and `series`. */
+export interface HeatmapGrid {
+	/** Ascending. N boundaries describe N+1 rows, including the `+Inf` overflow. */
+	bounds: number[];
+	/** Column starts, in seconds. */
+	timestamps: number[];
+	/** Column width in seconds. Cells span `[timestamps[j], timestamps[j] + step)`,
+	 *  and the last column has no successor to infer it from. */
+	step: number;
+	/** `counts[row][column]`, row 0 lowest. `null` (no data) renders hatched, `0`
+	 *  at the bottom of the scale — conflating them hides an outage. */
+	counts: Array<Array<number | null>>;
+}
+
+export interface HeatmapRow {
+	/** Synthetic on the underflow row. */
+	lower: number;
+	/** Synthetic on the overflow row. */
+	upper: number;
+	isUnderflow: boolean;
+	isOverflow: boolean;
+}
+
+/** The bucket axis in uPlot y-scale space. A log axis is log10 values on a
+ *  *linear* scale, not uPlot's log distribution, so boundaries stay exactly on
+ *  ticks and uPlot's decade-only label filter cannot hide them. */
+export interface HeatmapYAxis {
+	rows: HeatmapRow[];
+	/** Row edges, ascending. Length is `rows.length + 1`. */
+	edges: number[];
+	/** Real bucket boundaries — one tick each. */
+	splits: number[];
+	/** Where the `∞` tick goes: the overflow row's upper edge, not its centre,
+	 *  which would sit half a row from the last boundary and collide with it. */
+	overflowSplit: number | null;
+	toBucketValue: (axisValue: number) => number;
+	min: number;
+	max: number;
+}
+
+export interface HeatmapCell {
+	row: number;
+	column: number;
+	count: number | null;
+}

frontend/src/lib/visualization/charts/ChartWrapper/ChartWrapper.tsx

@@ -41,6 +41,9 @@ export default function ChartWrapper({
 	customTooltip,
 	pinnedTooltipElement,
 	tooltipPortalRoot,
+	customLegend,
+	legendLabels,
+	contentFooter,
 	'data-testid': testId,
 }: ChartWrapperProps): JSX.Element {
 	const plotInstanceRef = useRef<uPlot | null>(null);
@@ -61,6 +64,10 @@ export default function ChartWrapper({
 			if (!showLegend) {
 				return null;
 			}
+			// Charts whose legend does not list uPlot series supply their own.
+			if (customLegend) {
+				return customLegend(averageLegendWidth);
+			}
 			return (
 				<UPlotLegend
 					config={config}
@@ -69,7 +76,7 @@ export default function ChartWrapper({
 				/>
 			);
 		},
-		[config, legendConfig.position, showLegend],
+		[config, legendConfig.position, showLegend, customLegend],
 	);
 
 	const renderTooltipCallback = useCallback(
@@ -100,6 +107,8 @@ export default function ChartWrapper({
 				containerHeight={containerHeight}
 				legendConfig={legendConfig}
 				legendComponent={legendComponent}
+				seriesLabels={legendLabels}
+				contentFooter={contentFooter}
 				layoutChildren={layoutChildren}
 			>
 				{({ chartWidth, chartHeight, averageLegendWidth }): JSX.Element => (

frontend/src/lib/visualization/charts/Heatmap/Heatmap.tsx

@@ -0,0 +1,310 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+import ChartWrapper from 'lib/visualization/charts/ChartWrapper/ChartWrapper';
+import ColorBar from 'lib/uPlotV2/components/ColorBar/ColorBar';
+import Legend from 'lib/uPlotV2/components/Legend/Legend';
+import HeatmapTooltip from 'lib/uPlotV2/components/Tooltip/components/HeatmapTooltip/HeatmapTooltip';
+import {
+	LegendPosition,
+	TooltipRenderArgs,
+} from 'lib/uPlotV2/components/types';
+import {
+	createHeatmapColorResolver,
+	DEFAULT_HEATMAP_COLORS,
+	resolveCountDomain,
+	resolveExtremeColor,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/colorScale';
+import type { LegendItem } from 'lib/uPlotV2/config/types';
+import { resolveHeatmapYAxis } from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import {
+	resolveGroupPeaks,
+	resolveHeatmapGrid,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/grid';
+import {
+	HeatmapAxisScale,
+	HeatmapCell,
+	HeatmapColorMode,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+import { ChartClickData } from 'lib/uPlotV2/plugins/TooltipPlugin/types';
+
+import { HeatmapChartProps } from 'lib/visualization/charts/types';
+import { useHeatmapGroupLegend } from './useHeatmapGroupLegend';
+import { buildHeatmapConfig, prepareHeatmapChartData } from './utils';
+
+/** Vertical space the colour bar takes out of the container. */
+const COLOR_BAR_HEIGHT = 28;
+
+/**
+ * Columns are time slices, rows are bucket ranges, cell colour is the observation
+ * count — so a distribution can be watched changing shape instead of collapsing to
+ * percentile lines. Drawn on canvas (see `createHeatmapHooks`): a 40 × 240 grid is
+ * ~9,600 cells, far past what per-cell DOM carries.
+ */
+export default function Heatmap(props: HeatmapChartProps): JSX.Element {
+	const {
+		id,
+		buckets,
+		step,
+		series,
+		width,
+		height,
+		isDarkMode,
+		axisScale = HeatmapAxisScale.Log,
+		yAxisUnit,
+		decimalPrecision,
+		timezone,
+		showVisualMap = true,
+		showLegend = true,
+		legendPosition = LegendPosition.BOTTOM,
+		dimOnHover = true,
+		showTooltip = true,
+		canPinTooltip = false,
+		pinKey,
+		seriesColor,
+		minTimeScale,
+		maxTimeScale,
+		onDragSelect,
+		onCellClick,
+		renderTooltipFooter,
+		tooltipPortalRoot,
+		layoutChildren,
+		'data-testid': testId,
+	} = props;
+
+	const [hoveredCell, setHoveredCell] = useState<HeatmapCell | null>(null);
+	const hoveredCellRef = useRef<HeatmapCell | null>(null);
+	const onCellClickRef = useRef(onCellClick);
+	onCellClickRef.current = onCellClick;
+
+	const groups = useMemo(() => series.map((entry) => entry.label), [series]);
+
+	// One series has nothing to choose between.
+	const hasGroupLegend = showLegend && groups.length > 1;
+
+	const colors = useMemo(
+		() => ({ ...DEFAULT_HEATMAP_COLORS, ...props.colors }),
+		[props.colors],
+	);
+
+	// The opacity fill no longer follows a group colour: with several groups enabled
+	// at once there is no single one to follow.
+	const resolvedSeriesColor = seriesColor ?? DEFAULT_HEATMAP_COLORS.fill;
+
+	// Opacity mode keeps the solid fill; a partially transparent marker is hard to
+	// read against the panel.
+	const extremeColor = resolveExtremeColor({
+		options: colors,
+		isDarkMode,
+		seriesColor: resolvedSeriesColor,
+	});
+
+	const {
+		visibleGroups,
+		focusedSeriesIndex,
+		onLegendClick,
+		onLegendMouseMove,
+		onLegendMouseLeave,
+	} = useHeatmapGroupLegend({ groups });
+
+	const grid = useMemo(
+		() => resolveHeatmapGrid({ buckets, step, series, visibleGroups }),
+		[buckets, step, series, visibleGroups],
+	);
+
+	const yAxis = useMemo(
+		() => resolveHeatmapYAxis(grid.bounds, axisScale),
+		[grid.bounds, axisScale],
+	);
+
+	const hasGrid = yAxis.rows.length > 0 && grid.timestamps.length > 0;
+
+	const data = useMemo(
+		() =>
+			hasGrid
+				? prepareHeatmapChartData(grid, yAxis.rows.length)
+				: ([[]] as unknown as ReturnType<typeof prepareHeatmapChartData>),
+		[grid, yAxis.rows.length, hasGrid],
+	);
+
+	const colorResolver = useMemo(
+		() =>
+			createHeatmapColorResolver({
+				options: colors,
+				domain: resolveCountDomain(colors, grid.counts),
+				isDarkMode,
+				seriesColor: resolvedSeriesColor,
+			}),
+		[colors, grid.counts, isDarkMode, resolvedSeriesColor],
+	);
+
+	// Stable: the renderer captures it at config-build time, so a new identity would
+	// recreate the plot on every hover.
+	const handleHoverChange = useCallback((cell: HeatmapCell | null): void => {
+		hoveredCellRef.current = cell;
+		setHoveredCell(cell);
+	}, []);
+
+	const config = useMemo(
+		() =>
+			buildHeatmapConfig({
+				id,
+				grid,
+				yAxis,
+				colors,
+				isDarkMode,
+				seriesColor: resolvedSeriesColor,
+				dimOnHover,
+				onHoverChange: handleHoverChange,
+				yAxisUnit,
+				decimalPrecision,
+				timezone,
+				minTimeScale,
+				maxTimeScale,
+				onDragSelect,
+			}),
+		[
+			id,
+			grid,
+			yAxis,
+			colors,
+			isDarkMode,
+			resolvedSeriesColor,
+			dimOnHover,
+			handleHoverChange,
+			yAxisUnit,
+			decimalPrecision,
+			timezone,
+			minTimeScale,
+			maxTimeScale,
+			onDragSelect,
+		],
+	);
+
+	// Each marker takes the ramp colour for where that group's densest cell falls on
+	// the colour bar, so a swatch reads against the same scale as the grid.
+	const groupPeaks = useMemo(() => resolveGroupPeaks(series), [series]);
+	const isPaletteMode = colors.mode === HeatmapColorMode.Palette;
+
+	const legendItems = useMemo<LegendItem[]>(
+		() =>
+			groups.map((group, index) => ({
+				// +1 mirrors uPlot's 1-based data series, so the shared legend's index
+				// handling is identical across charts.
+				seriesIndex: index + 1,
+				label: group,
+				color: isPaletteMode
+					? (colorResolver.colorFor(groupPeaks.get(group) ?? 0) ?? extremeColor)
+					: extremeColor,
+				show: visibleGroups.includes(group),
+			})),
+		[
+			groups,
+			visibleGroups,
+			isPaletteMode,
+			colorResolver,
+			groupPeaks,
+			extremeColor,
+		],
+	);
+
+	const renderTooltip = useCallback(
+		(args: TooltipRenderArgs): React.ReactNode => (
+			<HeatmapTooltip
+				{...args}
+				id={id}
+				yAxis={yAxis}
+				step={grid.step}
+				series={series}
+				visibleGroups={visibleGroups}
+				groupColor={extremeColor}
+				yAxisUnit={yAxisUnit}
+				decimalPrecision={decimalPrecision}
+				timezone={timezone}
+				canPinTooltip={canPinTooltip}
+				renderTooltipFooter={renderTooltipFooter}
+			/>
+		),
+		[
+			id,
+			yAxis,
+			grid.step,
+			series,
+			visibleGroups,
+			extremeColor,
+			yAxisUnit,
+			decimalPrecision,
+			timezone,
+			canPinTooltip,
+			renderTooltipFooter,
+		],
+	);
+
+	const handleClick = useCallback((clickData: ChartClickData): void => {
+		if (hoveredCellRef.current) {
+			onCellClickRef.current?.(hoveredCellRef.current, clickData);
+		}
+	}, []);
+
+	const groupLegend = useCallback(
+		(averageLegendWidth: number): React.ReactNode => (
+			<Legend
+				items={legendItems}
+				position={legendPosition}
+				averageLegendWidth={averageLegendWidth}
+				focusedSeriesIndex={focusedSeriesIndex}
+				onClick={onLegendClick}
+				onMouseMove={onLegendMouseMove}
+				onMouseLeave={onLegendMouseLeave}
+			/>
+		),
+		[
+			legendItems,
+			legendPosition,
+			focusedSeriesIndex,
+			onLegendClick,
+			onLegendMouseMove,
+			onLegendMouseLeave,
+		],
+	);
+
+	const visualMap = useMemo(() => {
+		if (!showVisualMap || !hasGrid) {
+			return null;
+		}
+		return (
+			<ColorBar
+				label="count"
+				ramp={colorResolver.ramp}
+				minLabel={colorResolver.domain.min.toLocaleString()}
+				maxLabel={colorResolver.domain.max.toLocaleString()}
+				markerPosition={colorResolver.positionOf(hoveredCell?.count ?? null)}
+			/>
+		);
+	}, [showVisualMap, hasGrid, colorResolver, hoveredCell]);
+
+	return (
+		<ChartWrapper
+			config={config}
+			data={data}
+			width={width}
+			height={
+				showVisualMap && hasGrid ? Math.max(0, height - COLOR_BAR_HEIGHT) : height
+			}
+			legendConfig={{ position: legendPosition }}
+			showLegend={hasGroupLegend}
+			customLegend={groupLegend}
+			legendLabels={groups}
+			showTooltip={showTooltip}
+			canPinTooltip={canPinTooltip}
+			pinKey={pinKey}
+			onClick={onCellClick ? handleClick : undefined}
+			yAxisUnit={yAxisUnit}
+			decimalPrecision={decimalPrecision}
+			customTooltip={renderTooltip}
+			renderTooltipFooter={renderTooltipFooter}
+			tooltipPortalRoot={tooltipPortalRoot}
+			contentFooter={visualMap}
+			layoutChildren={layoutChildren}
+			data-testid={testId}
+		/>
+	);
+}

frontend/src/lib/visualization/charts/Heatmap/__tests__/Heatmap.test.tsx

@@ -0,0 +1,252 @@
+import type React from 'react';
+import userEvent from '@testing-library/user-event';
+import type { LegendItem } from 'lib/uPlotV2/config/types';
+import { render, screen } from 'tests/test-utils';
+import {
+	createHeatmapColorResolver,
+	DEFAULT_HEATMAP_COLORS,
+	resolveCountDomain,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/colorScale';
+import { resolveHeatmapGrid } from 'lib/uPlotV2/plugins/HeatmapPlugin/grid';
+import {
+	HeatmapColorMode,
+	HeatmapSeries,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+
+import Heatmap from '../Heatmap';
+
+// The shared Legend virtualises its items; render them all so they are queryable.
+jest.mock('react-virtuoso', () => ({
+	VirtuosoGrid: ({
+		data,
+		itemContent,
+	}: {
+		data: LegendItem[];
+		itemContent: (index: number, item: LegendItem) => React.ReactNode;
+	}): JSX.Element => (
+		<div>
+			{data.map((item, index) => (
+				<div key={item.seriesIndex}>{itemContent(index, item)}</div>
+			))}
+		</div>
+	),
+}));
+
+const BUCKETS = [128, 256, 1024];
+const STEP = 60;
+
+/** Two groups whose counts sum to a peak of 1,204 in the combined view. */
+const SERIES: HeatmapSeries[] = [
+	{
+		label: 'service.name=cart',
+		points: [
+			{ timestamp: 1000, counts: [1, 4, 7, 10] },
+			{ timestamp: 1060, counts: [2, null, 8, 11] },
+			{ timestamp: 1120, counts: [3, 6, 9, 1200] },
+		],
+	},
+	{
+		label: 'service.name=checkout',
+		points: [{ timestamp: 1120, counts: [0, 0, 0, 4] }],
+	},
+];
+
+function renderHeatmap(
+	props: Partial<React.ComponentProps<typeof Heatmap>> = {},
+): ReturnType<typeof render> {
+	return render(
+		<Heatmap
+			id="panel-1"
+			buckets={BUCKETS}
+			step={STEP}
+			series={SERIES}
+			width={800}
+			height={400}
+			isDarkMode
+			data-testid="heatmap"
+			{...props}
+		/>,
+	);
+}
+
+describe('Heatmap', () => {
+	it('renders the plot container', () => {
+		renderHeatmap();
+
+		expect(screen.getByTestId('heatmap')).toBeInTheDocument();
+	});
+
+	it('shows the colour bar with the resolved count domain', () => {
+		renderHeatmap();
+
+		expect(screen.getByTestId('color-bar')).toBeInTheDocument();
+		expect(screen.getByText('0')).toBeInTheDocument();
+		expect(screen.getByText('1,204')).toBeInTheDocument();
+	});
+
+	it('puts the colour bar against the plot, with the legend after it', () => {
+		renderHeatmap();
+
+		const bar = screen.getByTestId('color-bar');
+		const legend = screen.getByText('service.name=cart').closest('.legend-item');
+		// The bar is the scale key for the grid, so it reads before the controls.
+		expect(
+			bar.compareDocumentPosition(legend as Node) &
+				Node.DOCUMENT_POSITION_FOLLOWING,
+		).toBeTruthy();
+	});
+
+	it('keeps the colour bar inside the chart column, not below the legend', () => {
+		renderHeatmap();
+
+		expect(
+			screen.getByTestId('color-bar').closest('.chart-layout__content'),
+		).not.toBeNull();
+	});
+
+	it('hides the colour bar when the visual map is off', () => {
+		renderHeatmap({ showVisualMap: false });
+
+		expect(screen.queryByTestId('color-bar')).not.toBeInTheDocument();
+	});
+
+	it('labels the colour bar with an explicit clamp instead of the data range', () => {
+		renderHeatmap({ colors: { minCount: 5, maxCount: 500 } });
+
+		expect(screen.getByText('5')).toBeInTheDocument();
+		expect(screen.getByText('500')).toBeInTheDocument();
+	});
+
+	it('falls back to the no-data state when the metric has no buckets', () => {
+		renderHeatmap({ buckets: [] });
+
+		expect(screen.getByText('No Data')).toBeInTheDocument();
+		expect(screen.queryByTestId('color-bar')).not.toBeInTheDocument();
+	});
+
+	it('falls back to the no-data state when no columns came back', () => {
+		renderHeatmap({ series: [] });
+
+		expect(screen.getByText('No Data')).toBeInTheDocument();
+	});
+});
+
+describe('Heatmap group legend', () => {
+	const CART = 'service.name=cart';
+	const CHECKOUT = 'service.name=checkout';
+
+	function legendItem(label: string): HTMLElement {
+		const item = screen.getByText(label).closest('.legend-item');
+		if (!item) {
+			throw new Error(`no legend item for ${label}`);
+		}
+		return item as HTMLElement;
+	}
+
+	function marker(label: string): HTMLElement {
+		const element = legendItem(label).querySelector<HTMLElement>(
+			'[data-is-legend-marker]',
+		);
+		if (!element) {
+			throw new Error(`no marker for ${label}`);
+		}
+		return element;
+	}
+
+	it('lists the groups, with no combined-view entry', () => {
+		renderHeatmap();
+
+		expect(screen.getByText(CART)).toBeInTheDocument();
+		expect(screen.getByText(CHECKOUT)).toBeInTheDocument();
+		expect(screen.queryByText(/all groups/i)).not.toBeInTheDocument();
+	});
+
+	it('enables every group to begin with', () => {
+		renderHeatmap();
+
+		expect(legendItem(CART)).not.toHaveClass('legend-item-off');
+		expect(legendItem(CHECKOUT)).not.toHaveClass('legend-item-off');
+	});
+
+	it('isolates a group when its label is clicked', async () => {
+		renderHeatmap();
+
+		await userEvent.click(screen.getByText(CART));
+
+		expect(legendItem(CART)).not.toHaveClass('legend-item-off');
+		expect(legendItem(CHECKOUT)).toHaveClass('legend-item-off');
+	});
+
+	it('restores every group when the isolated label is clicked again', async () => {
+		renderHeatmap();
+
+		await userEvent.click(screen.getByText(CART));
+		await userEvent.click(screen.getByText(CART));
+
+		expect(legendItem(CHECKOUT)).not.toHaveClass('legend-item-off');
+	});
+
+	it('excludes just one group when its marker is clicked', async () => {
+		renderHeatmap();
+
+		await userEvent.click(marker(CHECKOUT));
+
+		expect(legendItem(CHECKOUT)).toHaveClass('legend-item-off');
+		expect(legendItem(CART)).not.toHaveClass('legend-item-off');
+	});
+
+	/** The ramp the cells and colour bar are drawn from, for the default options. */
+	function activeRamp(): string[] {
+		const grid = resolveHeatmapGrid({
+			buckets: BUCKETS,
+			step: STEP,
+			series: SERIES,
+		});
+		return createHeatmapColorResolver({
+			options: DEFAULT_HEATMAP_COLORS,
+			domain: resolveCountDomain(DEFAULT_HEATMAP_COLORS, grid.counts),
+			isDarkMode: true,
+			seriesColor: DEFAULT_HEATMAP_COLORS.fill,
+		}).ramp.map((color) => color.toLowerCase());
+	}
+
+	it('places each marker where its group sits on the colour bar', () => {
+		renderHeatmap();
+		const ramp = activeRamp();
+
+		// cart peaks at 1200, checkout at 4, so cart sits further along the ramp.
+		// The DOM lowercases hex; the ramp is built uppercase.
+		const cart = ramp.indexOf(marker(CART).style.borderColor.toLowerCase());
+		const checkout = ramp.indexOf(
+			marker(CHECKOUT).style.borderColor.toLowerCase(),
+		);
+
+		expect(cart).toBeGreaterThan(-1);
+		expect(checkout).toBeGreaterThan(-1);
+		expect(cart).toBeGreaterThan(checkout);
+	});
+
+	it('gives every marker the solid fill in opacity mode', () => {
+		renderHeatmap({
+			colors: { mode: HeatmapColorMode.Opacity, fill: '#e5484d' },
+		});
+
+		// A partially transparent marker is hard to read against the panel.
+		expect(marker(CART).style.borderColor).toBe(
+			marker(CHECKOUT).style.borderColor,
+		);
+		expect(marker(CART).style.borderColor).not.toBe('');
+	});
+
+	it('hides the legend when there is only one group to choose from', () => {
+		renderHeatmap({ series: [SERIES[0]] });
+
+		expect(screen.queryByText(CART)).not.toBeInTheDocument();
+	});
+
+	it('hides the legend when asked', () => {
+		renderHeatmap({ showLegend: false });
+
+		expect(screen.queryByText(CART)).not.toBeInTheDocument();
+	});
+});

frontend/src/lib/visualization/charts/Heatmap/__tests__/useHeatmapGroupLegend.test.ts

@@ -0,0 +1,147 @@
+import { act, renderHook } from '@testing-library/react';
+import type { MouseEvent } from 'react';
+
+import { useHeatmapGroupLegend } from '../useHeatmapGroupLegend';
+
+const GROUPS = ['cart', 'checkout', 'payments'];
+
+/** Mimics a click on an item's label, as the shared Legend renders it. */
+function labelClick(seriesIndex: number): MouseEvent<HTMLDivElement> {
+	const wrapper = document.createElement('div');
+	wrapper.setAttribute('data-legend-item-id', String(seriesIndex));
+	const label = document.createElement('span');
+	wrapper.appendChild(label);
+	return { target: label } as unknown as MouseEvent<HTMLDivElement>;
+}
+
+/** Mimics a click on the item's marker circle. */
+function markerClick(seriesIndex: number): MouseEvent<HTMLDivElement> {
+	const wrapper = document.createElement('div');
+	wrapper.setAttribute('data-legend-item-id', String(seriesIndex));
+	const marker = document.createElement('div');
+	marker.dataset.isLegendMarker = 'true';
+	wrapper.appendChild(marker);
+	return { target: marker } as unknown as MouseEvent<HTMLDivElement>;
+}
+
+function render(
+	groups: string[] = GROUPS,
+): ReturnType<
+	typeof renderHook<ReturnType<typeof useHeatmapGroupLegend>, unknown>
+> {
+	return renderHook(() => useHeatmapGroupLegend({ groups }));
+}
+
+describe('useHeatmapGroupLegend', () => {
+	it('enables every group to begin with', () => {
+		const { result } = render();
+
+		expect(result.current.visibleGroups).toStrictEqual(GROUPS);
+	});
+
+	it('isolates a group when its label is clicked', () => {
+		const { result } = render();
+
+		act(() => result.current.onLegendClick(labelClick(2)));
+
+		expect(result.current.visibleGroups).toStrictEqual(['checkout']);
+	});
+
+	it('restores every group when the isolated label is clicked again', () => {
+		const { result } = render();
+
+		act(() => result.current.onLegendClick(labelClick(2)));
+		act(() => result.current.onLegendClick(labelClick(2)));
+
+		expect(result.current.visibleGroups).toStrictEqual(GROUPS);
+	});
+
+	it('moves the isolation when a different label is clicked', () => {
+		const { result } = render();
+
+		act(() => result.current.onLegendClick(labelClick(1)));
+		act(() => result.current.onLegendClick(labelClick(3)));
+
+		expect(result.current.visibleGroups).toStrictEqual(['payments']);
+	});
+
+	it('excludes just one group when its marker is clicked', () => {
+		const { result } = render();
+
+		act(() => result.current.onLegendClick(markerClick(2)));
+
+		expect(result.current.visibleGroups).toStrictEqual(['cart', 'payments']);
+	});
+
+	it('re-includes a group when its marker is clicked again', () => {
+		const { result } = render();
+
+		act(() => result.current.onLegendClick(markerClick(2)));
+		act(() => result.current.onLegendClick(markerClick(2)));
+
+		expect(result.current.visibleGroups).toStrictEqual(GROUPS);
+	});
+
+	it('excludes more than one group', () => {
+		const { result } = render();
+
+		act(() => result.current.onLegendClick(markerClick(1)));
+		act(() => result.current.onLegendClick(markerClick(3)));
+
+		expect(result.current.visibleGroups).toStrictEqual(['checkout']);
+	});
+
+	it('drops the isolation when a marker is clicked, so the label can isolate again', () => {
+		const { result } = render();
+
+		act(() => result.current.onLegendClick(labelClick(1)));
+		// Re-including cart by marker leaves it enabled but no longer isolated.
+		act(() => result.current.onLegendClick(markerClick(2)));
+		act(() => result.current.onLegendClick(labelClick(1)));
+
+		expect(result.current.visibleGroups).toStrictEqual(['cart']);
+	});
+
+	it('allows every group to be excluded, as the other legends do', () => {
+		const { result } = render();
+
+		GROUPS.forEach((_, index) =>
+			act(() => result.current.onLegendClick(markerClick(index + 1))),
+		);
+
+		expect(result.current.visibleGroups).toStrictEqual([]);
+	});
+
+	it('ignores clicks that miss an entry', () => {
+		const { result } = render();
+		const stray = {
+			target: document.createElement('div'),
+		} as unknown as MouseEvent<HTMLDivElement>;
+
+		act(() => result.current.onLegendClick(stray));
+
+		expect(result.current.visibleGroups).toStrictEqual(GROUPS);
+	});
+
+	it('forgets a hidden group that left the result', () => {
+		const { result, rerender } = renderHook(
+			({ groups }) => useHeatmapGroupLegend({ groups }),
+			{ initialProps: { groups: GROUPS } },
+		);
+
+		act(() => result.current.onLegendClick(markerClick(3)));
+		rerender({ groups: ['cart', 'checkout'] });
+
+		expect(result.current.visibleGroups).toStrictEqual(['cart', 'checkout']);
+	});
+
+	it('tracks the hovered entry for the legend"s focus highlight', () => {
+		const { result } = render();
+
+		act(() => result.current.onLegendMouseMove(labelClick(2)));
+		expect(result.current.focusedSeriesIndex).toBe(2);
+
+		act(() => result.current.onLegendMouseLeave());
+		expect(result.current.focusedSeriesIndex).toBeNull();
+	});
+});

frontend/src/lib/visualization/charts/Heatmap/__tests__/utils.test.ts

@@ -0,0 +1,195 @@
+import { resolveHeatmapYAxis } from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import { DEFAULT_HEATMAP_COLORS } from 'lib/uPlotV2/plugins/HeatmapPlugin/colorScale';
+import {
+	HeatmapAxisScale,
+	HeatmapGrid,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+import type uPlot from 'uplot';
+
+import { buildHeatmapConfig, prepareHeatmapChartData } from '../utils';
+
+const GRID: HeatmapGrid = {
+	bounds: [128, 256, 1024],
+	timestamps: [1000, 1060, 1120],
+	step: 60,
+	counts: [
+		[1, 2, 3],
+		[4, null, 6],
+		[7, 8, 9],
+		[0, 0, 0],
+	],
+};
+
+const Y_AXIS = resolveHeatmapYAxis(GRID.bounds, HeatmapAxisScale.Log);
+
+/** Tall enough that no tick needs thinning. */
+const TALL_PLOT = { bbox: { height: 1000 } } as uPlot;
+
+function readSplits(
+	config: ReturnType<typeof buildHeatmapConfig>,
+	plot: uPlot,
+): number[] {
+	const [, yAxisConfig] = config.getConfig().axes ?? [];
+	return (yAxisConfig.splits as (self: uPlot) => number[])(plot);
+}
+
+function readLabels(
+	config: ReturnType<typeof buildHeatmapConfig>,
+	splits: number[],
+): string[] {
+	const [, yAxisConfig] = config.getConfig().axes ?? [];
+	return (yAxisConfig.values as (u: uPlot, splits: number[]) => string[])(
+		{} as uPlot,
+		splits,
+	);
+}
+
+function readRange(scale?: uPlot.Scale): [number, number] {
+	const range = scale?.range as (
+		u: uPlot,
+		min: number,
+		max: number,
+	) => [number, number];
+	return range({} as uPlot, 0, 0);
+}
+
+function buildConfig(
+	overrides: Partial<Parameters<typeof buildHeatmapConfig>[0]> = {},
+): ReturnType<typeof buildHeatmapConfig> {
+	return buildHeatmapConfig({
+		id: 'panel-1',
+		grid: GRID,
+		yAxis: Y_AXIS,
+		colors: DEFAULT_HEATMAP_COLORS,
+		isDarkMode: true,
+		seriesColor: '#4e74f8',
+		...overrides,
+	});
+}
+
+describe('prepareHeatmapChartData', () => {
+	it('puts timestamps first and one series per bucket row', () => {
+		const data = prepareHeatmapChartData(GRID, Y_AXIS.rows.length);
+
+		expect(data).toHaveLength(Y_AXIS.rows.length + 1);
+		expect(data[0]).toStrictEqual(GRID.timestamps);
+		expect(data[1]).toStrictEqual([1, 2, 3]);
+	});
+
+	it('preserves null cells rather than zeroing them', () => {
+		const data = prepareHeatmapChartData(GRID, Y_AXIS.rows.length);
+
+		expect(data[2]).toStrictEqual([4, null, 6]);
+	});
+
+	it('pads short rows so every uPlot data array is the same length', () => {
+		const data = prepareHeatmapChartData(
+			{ ...GRID, counts: [[1]] },
+			Y_AXIS.rows.length,
+		);
+
+		expect(data[1]).toStrictEqual([1, null, null]);
+	});
+
+	it('pads missing rows up to the resolved row count', () => {
+		const data = prepareHeatmapChartData({ ...GRID, counts: [] }, 2);
+
+		expect(data).toHaveLength(3);
+		expect(data[2]).toStrictEqual([null, null, null]);
+	});
+});
+
+describe('buildHeatmapConfig', () => {
+	it('registers one series per bucket row, plus uPlot"s timestamp series', () => {
+		const config = buildHeatmapConfig({
+			id: 'panel-1',
+			grid: GRID,
+			yAxis: Y_AXIS,
+			colors: DEFAULT_HEATMAP_COLORS,
+			isDarkMode: true,
+			seriesColor: '#4e74f8',
+		}).getConfig();
+
+		expect(config.series).toHaveLength(Y_AXIS.rows.length + 1);
+	});
+
+	it('draws no paths or points per series — the renderer paints the cells', () => {
+		const [, firstRow] = buildConfig().getConfig().series ?? [];
+
+		expect((firstRow as uPlot.Series).paths?.({} as uPlot, 1, 0, 1)).toBeNull();
+		expect((firstRow as uPlot.Series).points?.show).toBe(false);
+	});
+
+	it('labels series by bucket range, including the open-ended rows', () => {
+		const labels = (buildConfig().getConfig().series ?? [])
+			.slice(1)
+			.map((series) => series.label);
+
+		expect(labels[0]).toContain('≤');
+		expect(labels[labels.length - 1]).toContain('>');
+	});
+
+	it('spans the x scale to the end of the last column, not its start', () => {
+		const { x } = buildConfig().getConfig().scales ?? {};
+
+		expect(readRange(x)).toStrictEqual([1000, 1180]);
+	});
+
+	it('prefers the query window over the grid extent', () => {
+		const { x } =
+			buildConfig({ minTimeScale: 900, maxTimeScale: 1500 }).getConfig().scales ??
+			{};
+
+		expect(readRange(x)).toStrictEqual([900, 1500]);
+	});
+
+	it('pins the y scale to the bucket axis instead of auto-ranging on counts', () => {
+		const { y } = buildConfig().getConfig().scales ?? {};
+
+		expect(y?.auto).toBe(false);
+		expect(readRange(y)).toStrictEqual([Y_AXIS.min, Y_AXIS.max]);
+	});
+
+	it('puts a y tick on every bucket boundary plus the overflow row"s upper edge', () => {
+		const splits = readSplits(buildConfig(), TALL_PLOT);
+
+		expect(splits).toStrictEqual([...Y_AXIS.splits, Y_AXIS.overflowSplit]);
+	});
+
+	it('labels the overflow edge as infinite and the rest by bucket value', () => {
+		const config = buildConfig();
+		const labels = readLabels(config, readSplits(config, TALL_PLOT));
+
+		expect(labels[0]).toBe('128');
+		expect(labels[labels.length - 1]).toBe('∞');
+	});
+
+	it('thins the tick set when the panel is too short to label every boundary', () => {
+		const config = buildConfig();
+		const splits = readSplits(config, { bbox: { height: 40 } } as uPlot);
+
+		expect(splits.length).toBeLessThan(Y_AXIS.splits.length + 1);
+		// The infinite edge is the one label that must never be dropped.
+		expect(readLabels(config, splits).at(-1)).toBe('∞');
+	});
+
+	it('disables uPlot cursor focus and points, which cannot read a colour axis', () => {
+		const config = buildConfig().getConfig();
+
+		expect(config.cursor?.focus?.prox).toBe(-1);
+		expect(config.cursor?.points?.show).toBe(false);
+	});
+
+	it('keeps focus alpha at 1 so focusing a row does not force a full redraw', () => {
+		expect(buildConfig().getConfig().focus?.alpha).toBe(1);
+	});
+
+	it('registers the renderer hooks', () => {
+		const { hooks } = buildConfig().getConfig();
+
+		expect(hooks?.init).toHaveLength(1);
+		expect(hooks?.draw).toHaveLength(1);
+		expect(hooks?.setCursor).toHaveLength(1);
+		expect(hooks?.destroy).toHaveLength(1);
+	});
+});

frontend/src/lib/visualization/charts/Heatmap/useHeatmapGroupLegend.ts

@@ -0,0 +1,100 @@
+import { MouseEvent, useCallback, useMemo, useRef, useState } from 'react';
+
+export interface UseHeatmapGroupLegendResult {
+	/** Groups currently enabled. The grid sums exactly these. */
+	visibleGroups: string[];
+	focusedSeriesIndex: number | null;
+	onLegendClick: (event: MouseEvent<HTMLDivElement>) => void;
+	onLegendMouseMove: (event: MouseEvent<HTMLDivElement>) => void;
+	onLegendMouseLeave: () => void;
+}
+
+/** The shared Legend tags each item and delegates interaction to the container. */
+function getLegendIndex(event: MouseEvent<HTMLDivElement>): number | null {
+	const element = (event.target as HTMLElement | null)?.closest<HTMLElement>(
+		'[data-legend-item-id]',
+	);
+	const id = element?.dataset.legendItemId;
+	return id === undefined ? null : Number(id);
+}
+
+function isMarkerClick(event: MouseEvent<HTMLDivElement>): boolean {
+	return Boolean((event.target as HTMLElement).dataset.isLegendMarker);
+}
+
+/**
+ * Group visibility for the heatmap legend, matching every other legend in the
+ * product: the label isolates a group, the marker excludes one, and everything is
+ * enabled to begin with. Counts are additive, so whatever is enabled is summed
+ * client-side and needs no extra request.
+ *
+ * Visibility only. Marker colour is resolved by the caller, which owns the colour
+ * ramp — and that ramp depends on which groups this hook has enabled.
+ */
+export function useHeatmapGroupLegend({
+	groups,
+}: {
+	groups: string[];
+}): UseHeatmapGroupLegendResult {
+	const [hidden, setHidden] = useState<Set<string>>(() => new Set());
+	const [focusedSeriesIndex, setFocusedSeriesIndex] = useState<number | null>(
+		null,
+	);
+	const isolatedRef = useRef<string | null>(null);
+
+	const visibleGroups = useMemo(
+		() => groups.filter((group) => !hidden.has(group)),
+		[groups, hidden],
+	);
+
+	const onLegendClick = useCallback(
+		(event: MouseEvent<HTMLDivElement>): void => {
+			const index = getLegendIndex(event);
+			const group = index === null ? undefined : groups[index - 1];
+			if (group === undefined) {
+				return;
+			}
+
+			if (isMarkerClick(event)) {
+				isolatedRef.current = null;
+				setHidden((previous) => {
+					const next = new Set(previous);
+					if (next.has(group)) {
+						next.delete(group);
+					} else {
+						next.add(group);
+					}
+					return next;
+				});
+				return;
+			}
+
+			// Label click isolates; clicking the isolated group again restores all.
+			const isReset = isolatedRef.current === group;
+			isolatedRef.current = isReset ? null : group;
+			setHidden(
+				isReset ? new Set() : new Set(groups.filter((entry) => entry !== group)),
+			);
+		},
+		[groups],
+	);
+
+	const onLegendMouseMove = useCallback(
+		(event: MouseEvent<HTMLDivElement>): void => {
+			setFocusedSeriesIndex(getLegendIndex(event));
+		},
+		[],
+	);
+
+	const onLegendMouseLeave = useCallback((): void => {
+		setFocusedSeriesIndex(null);
+	}, []);
+
+	return {
+		visibleGroups,
+		focusedSeriesIndex,
+		onLegendClick,
+		onLegendMouseMove,
+		onLegendMouseLeave,
+	};
+}

frontend/src/lib/visualization/charts/Heatmap/utils.ts

@@ -0,0 +1,193 @@
+import { Timezone } from 'components/CustomTimePicker/timezoneUtils';
+import { PrecisionOption } from 'components/Graph/types';
+import { getToolTipValue } from 'components/Graph/yAxisConfig';
+import { uPlotXAxisValuesFormat } from 'lib/uPlotLib/utils/constants';
+import { DrawStyle } from 'lib/uPlotV2/config/types';
+import { UPlotConfigBuilder } from 'lib/uPlotV2/config/UPlotConfigBuilder';
+import {
+	decimateAxisSplits,
+	formatRowLabel,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/geometry';
+import {
+	createHeatmapHooks,
+	HeatmapRenderOptions,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/heatmapPlugin';
+import { HeatmapGrid } from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
+import uPlot from 'uplot';
+
+/** Minimum gap between y tick labels, in CSS pixels. */
+const MIN_Y_TICK_GAP_PX = 18;
+
+/** Label for the edge above the overflow row. */
+const OVERFLOW_AXIS_LABEL = '∞';
+
+/**
+ * Flattens the grid into `[timestamps, ...rows]`, one series per bucket row so
+ * `setData` handles refetches. The series draw nothing; the renderer paints cells.
+ *
+ * Rows are padded to `rowCount` — which can differ from `bounds.length + 1` when
+ * the response carried duplicate boundaries — since uPlot requires equal lengths.
+ */
+export function prepareHeatmapChartData(
+	grid: HeatmapGrid,
+	rowCount: number,
+): uPlot.AlignedData {
+	const columnCount = grid.timestamps.length;
+	const rows = Array.from({ length: rowCount }, (_, row) => {
+		const counts = grid.counts[row] ?? [];
+		return Array.from({ length: columnCount }, (_, column) =>
+			counts[column] === undefined ? null : counts[column],
+		);
+	});
+
+	return [grid.timestamps, ...rows] as unknown as uPlot.AlignedData;
+}
+
+export interface BuildHeatmapConfigArgs extends Omit<
+	HeatmapRenderOptions,
+	'step'
+> {
+	id: string;
+	grid: HeatmapGrid;
+	/** Unit of the bucket boundaries; counts are never formatted with it. */
+	yAxisUnit?: string;
+	decimalPrecision?: PrecisionOption;
+	timezone?: Timezone;
+	/** Query window, in seconds. Falls back to the grid's own extent. */
+	minTimeScale?: number;
+	maxTimeScale?: number;
+	onDragSelect?: (startTime: number, endTime: number) => void;
+}
+
+export function buildHeatmapConfig({
+	id,
+	grid,
+	yAxis,
+	colors,
+	isDarkMode,
+	seriesColor,
+	dimOnHover,
+	onHoverChange,
+	yAxisUnit,
+	decimalPrecision,
+	timezone,
+	minTimeScale,
+	maxTimeScale,
+	onDragSelect,
+}: BuildHeatmapConfigArgs): UPlotConfigBuilder {
+	const tzDate = timezone
+		? (timestamp: number): Date =>
+				uPlot.tzDate(new Date(timestamp * 1e3), timezone.value)
+		: undefined;
+
+	const builder = new UPlotConfigBuilder({ id, onDragSelect, tzDate });
+
+	// uPlot's focus picks the series closest in value space, meaningless when the
+	// value is a colour; the renderer focuses the hovered row itself. alpha 1 keeps
+	// that call off uPlot's full-redraw path.
+	builder.setFocus({ alpha: 1 });
+	builder.setCursor({ focus: { prox: -1 }, points: { show: false } });
+
+	const formatBucketValue = (value: number): string =>
+		getToolTipValue(String(value), yAxisUnit, decimalPrecision);
+
+	const lastTimestamp = grid.timestamps[grid.timestamps.length - 1] ?? 0;
+	const xRange: [number, number] = [
+		minTimeScale ?? grid.timestamps[0] ?? 0,
+		maxTimeScale ?? lastTimestamp + grid.step,
+	];
+
+	builder.addScale({
+		scaleKey: 'x',
+		time: true,
+		range: (): [number, number] => xRange,
+	});
+	builder.addScale({
+		scaleKey: 'y',
+		time: false,
+		auto: false,
+		range: (): [number, number] => [yAxis.min, yAxis.max],
+	});
+
+	builder.addAxis({
+		scaleKey: 'x',
+		side: 2,
+		isDarkMode,
+		values: uPlotXAxisValuesFormat as uPlot.Axis.Values,
+	});
+
+	// Ticks sit on row edges, so the overflow row is the band between the last
+	// boundary and `∞`. A centre label would sit half a row from the boundary tick
+	// and collide with it.
+	const overflowRow = yAxis.rows[yAxis.rows.length - 1];
+	const hasOverflowTick =
+		yAxis.overflowSplit !== null && overflowRow?.isOverflow === true;
+	const axisSplits = hasOverflowTick
+		? [...yAxis.splits, yAxis.overflowSplit as number]
+		: yAxis.splits;
+
+	// From the boundaries themselves, not by inverting the transform:
+	// 10 ** Math.log10(128) is 127.999…, which formats as "127.99".
+	const splitLabels = new Map<number, string>();
+	yAxis.splits.forEach((split, index) => {
+		splitLabels.set(split, formatBucketValue(yAxis.rows[index].upper));
+	});
+	if (hasOverflowTick) {
+		splitLabels.set(yAxis.overflowSplit as number, OVERFLOW_AXIS_LABEL);
+	}
+
+	builder.addAxis({
+		scaleKey: 'y',
+		side: 3,
+		isDarkMode,
+		yAxisUnit,
+		decimalPrecision,
+		// Thinned to whatever fits: a histogram can carry more boundaries than the
+		// panel has room to label.
+		splits: (self): number[] =>
+			decimateAxisSplits({
+				splits: axisSplits,
+				min: yAxis.min,
+				max: yAxis.max,
+				plotHeight: self.bbox.height / uPlot.pxRatio,
+				minGapPx: MIN_Y_TICK_GAP_PX,
+			}),
+		values: (_, splits): string[] =>
+			splits.map(
+				(split) =>
+					splitLabels.get(split) ?? formatBucketValue(yAxis.toBucketValue(split)),
+			),
+	});
+
+	yAxis.rows.forEach((row) => {
+		builder.addSeries({
+			scaleKey: 'y',
+			// Nothing is stroked per series; the draw hook paints the grid.
+			drawStyle: DrawStyle.Line,
+			pathBuilder: (): null => null,
+			showPoints: false,
+			spanGaps: false,
+			label: formatRowLabel(row, formatBucketValue),
+			colorMapping: {},
+			isDarkMode,
+		});
+	});
+
+	const hooks = createHeatmapHooks({
+		yAxis,
+		step: grid.step,
+		colors,
+		isDarkMode,
+		seriesColor,
+		dimOnHover,
+		onHoverChange,
+	});
+
+	// Order matters — see the HeatmapHooks doc comment.
+	builder.addHook('init', hooks.init);
+	builder.addHook('draw', hooks.draw);
+	builder.addHook('setCursor', hooks.setCursor);
+	builder.addHook('destroy', hooks.destroy);
+
+	return builder;
+}

frontend/src/lib/visualization/charts/Pie/Pie.tsx

@@ -45,7 +45,9 @@ export default function Pie({
 		visibleData,
 		legendItems,
 		focusedSeriesIndex,
-		onLegendAction,
+		onLegendClick,
+		onLegendMouseMove,
+		onLegendMouseLeave,
 	} = usePieInteractions(data, id);
 
 	const {
@@ -225,7 +227,9 @@ export default function Pie({
 					position={position}
 					averageLegendWidth={averageLegendWidth}
 					focusedSeriesIndex={focusedSeriesIndex}
-					onAction={onLegendAction}
+					onClick={onLegendClick}
+					onMouseMove={onLegendMouseMove}
+					onMouseLeave={onLegendMouseLeave}
 				/>
 			</div>
 		</div>

frontend/src/lib/visualization/charts/Pie/__tests__/Pie.test.tsx

@@ -100,29 +100,17 @@ describe('Pie', () => {
 		expect(screen.getByTestId('pie')).toHaveStyle({ flexDirection: 'column' });
 	});
 
-	it('isolates a slice when its legend row is clicked with everything showing', () => {
+	it('hides a slice when its legend marker is clicked', () => {
 		renderPie();
 		const svg = screen.getByTestId('pie').querySelector('svg') as SVGElement;
 		expect(svg.querySelectorAll('path')).toHaveLength(3);
 
-		fireEvent.click(screen.getByTestId('legend-item-1'));
-
-		// Nothing visible to exclude, so the click isolates: one arc left.
-		expect(svg.querySelectorAll('path')).toHaveLength(1);
-	});
-
-	it('excludes a slice when its legend row is clicked with others already hidden', () => {
-		renderPie();
-		const svg = screen.getByTestId('pie').querySelector('svg') as SVGElement;
-
-		// Isolate, then add a second slice back, so nothing is isolated any more.
-		fireEvent.click(screen.getByTestId('legend-item-1'));
-		fireEvent.click(screen.getByTestId('legend-item-0'));
-		expect(svg.querySelectorAll('path')).toHaveLength(2);
-
-		fireEvent.click(screen.getByTestId('legend-item-0'));
+		const marker = document.querySelector(
+			'[data-legend-item-id="1"] [data-is-legend-marker="true"]',
+		) as HTMLElement;
+		fireEvent.click(marker);
 
 		// One slice hidden → one fewer arc drawn.
-		expect(svg.querySelectorAll('path')).toHaveLength(1);
+		expect(svg.querySelectorAll('path')).toHaveLength(2);
 	});
 });

frontend/src/lib/visualization/charts/__tests__/utils.test.ts

@@ -1,9 +1,6 @@
 import { LegendPosition } from 'lib/uPlotV2/components/types';
 
-import {
-	calculateAverageLegendWidth,
-	calculateChartDimensions,
-} from 'lib/visualization/charts/utils';
+import { calculateChartDimensions } from 'lib/visualization/charts/utils';
 
 const labels = (count: number, length = 20): string[] =>
 	Array.from({ length: count }, (_, i) =>
@@ -52,104 +49,63 @@ describe('calculateChartDimensions', () => {
 		expect(dims.width).toBe(784);
 	});
 
-	it('RIGHT: never shrinks the column below the floor that fits its chrome', () => {
+	it('RIGHT: never shrinks the column below the 150px floor', () => {
 		const dims = calculateChartDimensions({
 			containerWidth: 1000,
 			containerHeight: 400,
 			legendConfig: { position: LegendPosition.RIGHT },
 			seriesLabels: labels(3, 3),
 		});
-		expect(dims.legendWidth).toBe(190);
-		expect(dims.width).toBe(810);
+		expect(dims.legendWidth).toBe(150);
+		expect(dims.width).toBe(850);
 	});
 
-	it('RIGHT: on a narrow container the legend keeps its chrome, up to half the width', () => {
+	it('RIGHT: on a narrow container the legend never takes more than 40% of the width', () => {
 		const dims = calculateChartDimensions({
 			containerWidth: 300,
 			containerHeight: 400,
 			legendConfig: { position: LegendPosition.RIGHT },
 			seriesLabels: labels(10, 40),
 		});
-		// 40% is 120px, too narrow for the column's own toolbar.
-		expect(dims.legendWidth).toBe(150);
-		expect(dims.width).toBe(150);
+		expect(dims.legendWidth).toBe(120);
+		expect(dims.width).toBe(180);
 	});
 
-	it('RIGHT: stops widening the column once the panel is narrower than its chrome', () => {
-		const dims = calculateChartDimensions({
-			containerWidth: 200,
-			containerHeight: 400,
-			legendConfig: { position: LegendPosition.RIGHT },
-			seriesLabels: labels(10, 40),
-		});
-		expect(dims.legendWidth).toBe(100);
-		expect(dims.width).toBe(100);
-	});
-
-	it('BOTTOM: items that fit one row reserve exactly one row', () => {
+	it('BOTTOM: a single row of items reserves one legend row', () => {
 		const dims = calculateChartDimensions({
 			containerWidth: 1000,
 			containerHeight: 500,
 			legendConfig: { position: LegendPosition.BOTTOM },
 			seriesLabels: labels(3),
 		});
-		// One 28px row + the wrapper's 12px bottom padding.
+		// One row = line height (28) + padding (12).
 		expect(dims.legendHeight).toBe(40);
 		expect(dims.height).toBe(460);
 		expect(dims.legendWidth).toBe(1000);
 	});
 
-	it('BOTTOM: more items than one row reserve exactly two rows', () => {
+	it('BOTTOM: many items cap at two rows on a tall container', () => {
 		const dims = calculateChartDimensions({
 			containerWidth: 1000,
 			containerHeight: 500,
 			legendConfig: { position: LegendPosition.BOTTOM },
 			seriesLabels: labels(40),
 		});
-		// Two 28px rows + the 2px row gap + 12px bottom padding — no room for a
-		// clipped third row, and none left over.
-		expect(dims.legendHeight).toBe(70);
-		expect(dims.height).toBe(430);
+		// Two rows = 2 * 40 - 12 (no trailing padding) = 68, under the 80px cap.
+		expect(dims.legendHeight).toBe(68);
+		expect(dims.height).toBe(432);
 	});
 
-	it('BOTTOM: items one past a row still reserve two rows', () => {
-		// 1000px wide fits 5 of these per row, so 6 items need a second row.
+	it('BOTTOM: on a short container the legend never takes more than 30% of the height', () => {
 		const dims = calculateChartDimensions({
 			containerWidth: 1000,
-			containerHeight: 500,
-			legendConfig: { position: LegendPosition.BOTTOM },
-			seriesLabels: labels(6),
-		});
-		expect(dims.legendHeight).toBe(70);
-	});
-
-	it('BOTTOM: drops to a single row rather than take half a short panel', () => {
-		const dims = calculateChartDimensions({
-			containerWidth: 1000,
-			containerHeight: 120,
+			containerHeight: 160,
 			legendConfig: { position: LegendPosition.BOTTOM },
 			seriesLabels: labels(40),
 		});
-		// A whole row goes rather than a clipped one being reserved.
-		expect(dims.legendHeight).toBe(40);
-		expect(dims.height).toBe(80);
-	});
-});
-
-describe('calculateAverageLegendWidth', () => {
-	it('scales with the label length', () => {
-		// 16px of chrome + 30 chars at 8px.
-		expect(calculateAverageLegendWidth(labels(4, 30))).toBe(256);
-	});
-
-	it('never drops below what a row needs to contain its hover actions', () => {
-		// Short or unnamed series would otherwise size a column the actions
-		// escape, spilling over the item beside it.
-		expect(calculateAverageLegendWidth(['cpu'])).toBe(110);
-		expect(calculateAverageLegendWidth([''])).toBe(110);
-	});
-
-	it('keeps the default estimate when there are no labels to measure', () => {
-		expect(calculateAverageLegendWidth([])).toBe(120);
+		// Without the height-relative cap the legend would take 68px of a 160px
+		// panel and the chart (pie especially) collapses to a sliver.
+		expect(dims.legendHeight).toBe(48); // 30% of 160
+		expect(dims.height).toBe(112);
 	});
 });

frontend/src/lib/visualization/charts/types.ts

@@ -9,6 +9,12 @@ import {
 	TooltipRenderArgs,
 } from 'lib/uPlotV2/components/types';
 import { UPlotConfigBuilder } from 'lib/uPlotV2/config/UPlotConfigBuilder';
+import type {
+	HeatmapAxisScale,
+	HeatmapCell,
+	HeatmapColorOptions,
+	HeatmapSeries,
+} from 'lib/uPlotV2/plugins/HeatmapPlugin/types';
 import {
 	DashboardCursorSync,
 	SyncTooltipFilterMode,
@@ -33,6 +39,13 @@ interface BaseChartProps {
 	renderTooltipFooter?: (args: IRenderTooltipFooterArgs) => React.ReactNode;
 	customTooltip?: (props: TooltipRenderArgs) => React.ReactNode;
 	tooltipPortalRoot?: HTMLElement | null;
+	/** Replaces the config-driven legend, for charts whose legend lists something
+	 *  other than uPlot series — heatmap groups, where the series are bucket rows. */
+	customLegend?: (averageLegendWidth: number) => React.ReactNode;
+	/** Measured against for the chart/legend split. Pair with `customLegend`. */
+	legendLabels?: string[];
+	/** Rendered under the plot but above the legend, inside the chart column. */
+	contentFooter?: React.ReactNode;
 	'data-testid'?: string;
 }
 interface UPlotBasedChartProps {
@@ -74,6 +87,60 @@ export interface HistogramChartProps extends ChartWrapperProps {
 	isQueriesMerged?: boolean;
 }
 
+/**
+ * Data arrives as the query response carries it — bucket bounds plus one series per
+ * group — and the chart pivots and sums it, so no caller has to get the transpose
+ * or the combined view right. It builds its own `UPlotConfigBuilder` too, since the
+ * y axis *is* the bucket axis and `buckets` fully determines it.
+ *
+ * `buckets`, `series` and `colors` must be referentially stable: a new identity
+ * rebuilds the config, which recreates the plot.
+ */
+export interface HeatmapChartProps {
+	id: string;
+	/** Ascending. N boundaries describe N+1 rows. */
+	buckets: number[];
+	/** The *effective* step the server used (`meta.stepIntervals[queryName]`), not
+	 *  the requested one. Cannot be inferred: the last column has no successor. */
+	step: number;
+	/** One entry per group; a query without grouping yields one series. */
+	series: HeatmapSeries[];
+	width: number;
+	height: number;
+	isDarkMode: boolean;
+	/** Overrides on top of `DEFAULT_HEATMAP_COLORS`. */
+	colors?: Partial<HeatmapColorOptions>;
+	/** Default log. */
+	axisScale?: HeatmapAxisScale;
+	/** Unit of the bucket boundaries; counts are always plain numbers. */
+	yAxisUnit?: string;
+	decimalPrecision?: PrecisionOption;
+	timezone?: Timezone;
+	/** Colour bar below the grid. Default true. */
+	showVisualMap?: boolean;
+	/** Default true; hidden anyway when there is only one group. Every group starts
+	 *  enabled — the label isolates one, the marker excludes one. */
+	showLegend?: boolean;
+	legendPosition?: LegendPosition;
+	/** Default true. */
+	dimOnHover?: boolean;
+	showTooltip?: boolean;
+	canPinTooltip?: boolean;
+	pinKey?: string;
+	/** Overrides the opacity-mode fill, which otherwise follows the selected
+	 *  group's legend colour so the grid matches the swatch that was clicked. */
+	seriesColor?: string;
+	/** Query window, in seconds. Falls back to the data's own extent. */
+	minTimeScale?: number;
+	maxTimeScale?: number;
+	onDragSelect?: (startTime: number, endTime: number) => void;
+	onCellClick?: (cell: HeatmapCell, clickData: ChartClickData) => void;
+	renderTooltipFooter?: (args: IRenderTooltipFooterArgs) => React.ReactNode;
+	tooltipPortalRoot?: HTMLElement | null;
+	layoutChildren?: React.ReactNode;
+	'data-testid'?: string;
+}
+
 /**
  * One resolved pie/donut slice: a display label, its (already parsed) positive
  * numeric value, and the colour used for the arc + legend swatch.

frontend/src/lib/visualization/charts/utils.ts

@@ -1,10 +1,4 @@
-import {
-	LEGEND_MAX_BOTTOM_ROWS,
-	MIN_LEGEND_ITEM_WIDTH,
-	LEGEND_ROW_GAP,
-	LEGEND_ROW_HEIGHT,
-	MAX_LEGEND_WIDTH,
-} from 'lib/uPlotV2/components/Legend/constants';
+import { MAX_LEGEND_WIDTH } from 'lib/uPlotV2/components/Legend/Legend';
 import { LegendConfig, LegendPosition } from 'lib/uPlotV2/components/types';
 export interface ChartDimensions {
 	width: number;
@@ -19,31 +13,22 @@ const LEGEND_WIDTH_PERCENTILE = 0.85;
 const DEFAULT_AVG_LABEL_LENGTH = 15;
 const BASE_LEGEND_WIDTH = 16;
 const LEGEND_PADDING = 12;
-// Two rows are worth having, but not at the cost of half the panel.
-const MAX_SHORT_PANEL_LEGEND_RATIO = 0.5;
+const LEGEND_LINE_HEIGHT = 28;
 
 // RIGHT legend is a vertical column with its own width budget (cap protects the donut).
 const MAX_RIGHT_LEGEND_WIDTH = 320;
 const RIGHT_LEGEND_WIDTH_RATIO = 0.4;
 // Column padding + copy button, not covered by the text-length estimate.
 const RIGHT_LEGEND_RESERVED_WIDTH = 40;
-// Fits the toolbar's "Showing N of M series" readout plus the wrapper padding.
-const MIN_RIGHT_LEGEND_WIDTH = 190;
-// Past this the split inverts and the chart becomes the smaller half.
-const RIGHT_LEGEND_FLOOR_RATIO = 0.5;
 
 /**
  * Calculates the average width of the legend items based on the labels of the series.
- * Never returns less than a legend row needs to hold its own hover actions.
  * @param legends - The labels of the series.
  * @returns The average width of the legend items.
  */
 export function calculateAverageLegendWidth(legends: string[]): number {
 	if (legends.length === 0) {
-		return Math.max(
-			MIN_LEGEND_ITEM_WIDTH,
-			DEFAULT_AVG_LABEL_LENGTH * AVG_CHAR_WIDTH,
-		);
+		return DEFAULT_AVG_LABEL_LENGTH * AVG_CHAR_WIDTH;
 	}
 
 	const lengths = legends.map((l) => l.length).sort((a, b) => a - b);
@@ -51,10 +36,7 @@ export function calculateAverageLegendWidth(legends: string[]): number {
 	const index = Math.ceil(LEGEND_WIDTH_PERCENTILE * lengths.length) - 1;
 	const percentileLength = lengths[Math.max(0, index)];
 
-	return Math.max(
-		MIN_LEGEND_ITEM_WIDTH,
-		BASE_LEGEND_WIDTH + percentileLength * AVG_CHAR_WIDTH,
-	);
+	return BASE_LEGEND_WIDTH + percentileLength * AVG_CHAR_WIDTH;
 }
 
 /**
@@ -70,9 +52,7 @@ export function calculateAverageLegendWidth(legends: string[]): number {
  *   - Chart width is `containerWidth - legendWidth`.
  * - BOTTOM legend:
  *   - Computes how many items fit per row, then uses at most 2 rows.
- *   - `legendHeight` is exactly those rows plus the wrapper's bottom padding, so
- *     the rectangle never clips a row or reserves space for half of one. Two
- *     rows that would take half a short panel fall back to one row.
+ *   - `legendHeight` is derived from row count, capped by both a fixed pixel max and a % of container height.
  *   - Chart height is `containerHeight - legendHeight`, never below 0.
  * - `legendsPerSet` is the number of legend items that fit horizontally, based on the same text-width approximation.
  *
@@ -120,14 +100,9 @@ export function calculateChartDimensions({
 			MAX_RIGHT_LEGEND_WIDTH,
 			containerWidth * RIGHT_LEGEND_WIDTH_RATIO,
 		);
-		// The column's chrome outranks the 40% share on a narrow panel.
-		const floorWidth = Math.min(
-			MIN_RIGHT_LEGEND_WIDTH,
-			containerWidth * RIGHT_LEGEND_FLOOR_RATIO,
-		);
 		const rightLegendWidth = Math.min(
-			Math.max(MIN_RIGHT_LEGEND_WIDTH, desiredLegendWidth),
-			Math.max(floorWidth, maxRightLegendWidth),
+			Math.max(150, desiredLegendWidth),
+			maxRightLegendWidth,
 		);
 
 		return {
@@ -140,6 +115,8 @@ export function calculateChartDimensions({
 		};
 	}
 
+	const legendRowHeight = LEGEND_LINE_HEIGHT + LEGEND_PADDING;
+
 	const legendItemWidth = Math.ceil(
 		Math.min(approxLegendItemWidth, MAX_LEGEND_WIDTH),
 	);
@@ -148,30 +125,30 @@ export function calculateChartDimensions({
 		Math.floor((containerWidth - LEGEND_PADDING * 2) / legendItemWidth),
 	);
 
-	// The wrapper's bottom padding is inside this height (border-box).
-	const heightForRows = (rowCount: number): number =>
-		rowCount * LEGEND_ROW_HEIGHT +
-		(rowCount - 1) * LEGEND_ROW_GAP +
-		LEGEND_PADDING;
-
-	const neededRowCount = Math.max(
-		1,
-		Math.min(
-			LEGEND_MAX_BOTTOM_ROWS,
-			Math.ceil(legendItemCount / legendItemsPerRow),
-		),
+	const legendRowCount = Math.min(
+		2,
+		Math.ceil(legendItemCount / legendItemsPerRow),
 	);
 
-	// Without this, short grid panels hand most of their area to the legend and
-	// the chart — the pie donut especially — collapses to a sliver. Dropping a
-	// whole row beats clipping one.
-	const legendRowCount =
-		neededRowCount > 1 &&
-		heightForRows(neededRowCount) > containerHeight * MAX_SHORT_PANEL_LEGEND_RATIO
-			? 1
-			: neededRowCount;
+	const idealBottomLegendHeight =
+		legendRowCount > 1
+			? legendRowCount * legendRowHeight - LEGEND_PADDING
+			: legendRowHeight;
 
-	const bottomLegendHeight = heightForRows(legendRowCount);
+	// Cap at two rows / 80px, and never more than 30% of the container height
+	// (the doc above always promised the %-cap; without it, short grid panels
+	// hand most of their area to the legend and the chart — the pie donut
+	// especially — collapses to a sliver). 30% mirrors the RIGHT-legend width cap.
+	const maxAllowedLegendHeight = Math.min(
+		2 * legendRowHeight,
+		80,
+		Math.floor(containerHeight * 0.3),
+	);
+
+	const bottomLegendHeight = Math.min(
+		idealBottomLegendHeight,
+		maxAllowedLegendHeight,
+	);
 
 	return {
 		width: containerWidth,

frontend/src/lib/visualization/hooks/__tests__/usePieInteractions.test.tsx

@@ -1,9 +1,9 @@
 import { act, renderHook } from '@testing-library/react';
-import { LegendAction } from 'lib/uPlotV2/components/types';
 import {
 	getStoredSeriesVisibility,
 	updateSeriesVisibilityToLocalStorage,
 } from 'lib/visualization/panels/utils/legendVisibilityUtils';
+import type { MouseEvent } from 'react';
 
 import { PieSlice } from 'lib/visualization/charts/types';
 import { usePieInteractions } from 'lib/visualization/hooks/usePieInteractions';
@@ -24,6 +24,22 @@ const DATA: PieSlice[] = [
 	{ label: 'checkout', value: 40, color: '#c' },
 ];
 
+// Builds a fake legend click/move event: `e.target.closest('[data-legend-item-id]')`
+// resolves to the item at `index`, and `e.target.dataset.isLegendMarker` flags marker clicks.
+function legendEvent(
+	index: number | null,
+	isMarker = false,
+): MouseEvent<HTMLDivElement> {
+	const itemEl =
+		index == null ? null : { dataset: { legendItemId: String(index) } };
+	return {
+		target: {
+			closest: (): unknown => itemEl,
+			dataset: { isLegendMarker: isMarker ? 'true' : undefined },
+		},
+	} as unknown as MouseEvent<HTMLDivElement>;
+}
+
 describe('usePieInteractions', () => {
 	beforeEach(() => {
 		mockGetStored.mockReturnValue(null);
@@ -43,16 +59,11 @@ describe('usePieInteractions', () => {
 		expect(result.current.active).toBeNull();
 	});
 
-	describe('row toggle', () => {
+	describe('marker click (toggle one)', () => {
 		it('hides then unhides the clicked slice', () => {
 			const { result } = renderHook(() => usePieInteractions(DATA, 'panel-1'));
 
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.TOGGLE,
-					seriesIndex: 1,
-				}),
-			);
+			act(() => result.current.onLegendClick(legendEvent(1, true)));
 
 			expect(result.current.visibleData).toStrictEqual([DATA[0], DATA[2]]);
 			expect(result.current.legendItems[1].show).toBe(false);
@@ -62,50 +73,18 @@ describe('usePieInteractions', () => {
 				{ label: 'checkout', show: true },
 			]);
 
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.TOGGLE,
-					seriesIndex: 1,
-				}),
-			);
+			act(() => result.current.onLegendClick(legendEvent(1, true)));
 
 			expect(result.current.visibleData).toStrictEqual(DATA);
 			expect(result.current.legendItems[1].show).toBe(true);
 		});
 	});
 
-	describe('the last slice showing', () => {
-		it('cannot be hidden', () => {
+	describe('label click (isolate / reset)', () => {
+		it('isolates the clicked slice, then resets on a second click', () => {
 			const { result } = renderHook(() => usePieInteractions(DATA));
 
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.SHOW_ONLY,
-					seriesIndex: 0,
-				}),
-			);
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.TOGGLE,
-					seriesIndex: 0,
-				}),
-			);
-
-			// An empty donut is never a state worth reaching.
-			expect(result.current.visibleData).toStrictEqual([DATA[0]]);
-		});
-	});
-
-	describe('Only', () => {
-		it('isolates the slice', () => {
-			const { result } = renderHook(() => usePieInteractions(DATA));
-
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.SHOW_ONLY,
-					seriesIndex: 0,
-				}),
-			);
+			act(() => result.current.onLegendClick(legendEvent(0, false)));
 
 			expect(result.current.visibleData).toStrictEqual([DATA[0]]);
 			expect(result.current.legendItems.map((i) => i.show)).toStrictEqual([
@@ -113,39 +92,8 @@ describe('usePieInteractions', () => {
 				false,
 				false,
 			]);
-		});
 
-		it('switches the isolation to another slice', () => {
-			const { result } = renderHook(() => usePieInteractions(DATA));
-
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.SHOW_ONLY,
-					seriesIndex: 0,
-				}),
-			);
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.SHOW_ONLY,
-					seriesIndex: 2,
-				}),
-			);
-
-			expect(result.current.visibleData).toStrictEqual([DATA[2]]);
-		});
-	});
-
-	describe('All', () => {
-		it('brings every hidden slice back', () => {
-			const { result } = renderHook(() => usePieInteractions(DATA));
-
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.SHOW_ONLY,
-					seriesIndex: 0,
-				}),
-			);
-			act(() => result.current.onLegendAction({ type: LegendAction.SHOW_ALL }));
+			act(() => result.current.onLegendClick(legendEvent(0, false)));
 
 			expect(result.current.visibleData).toStrictEqual(DATA);
 		});
@@ -155,37 +103,11 @@ describe('usePieInteractions', () => {
 		it('focuses the hovered slice and clears on leave', () => {
 			const { result } = renderHook(() => usePieInteractions(DATA));
 
-			act(() =>
-				result.current.onLegendAction({ type: LegendAction.HOVER, seriesIndex: 2 }),
-			);
+			act(() => result.current.onLegendMouseMove(legendEvent(2)));
 			expect(result.current.active).toStrictEqual(DATA[2]);
 			expect(result.current.focusedSeriesIndex).toBe(2);
 
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.HOVER,
-					seriesIndex: null,
-				}),
-			);
-			expect(result.current.active).toBeNull();
-			expect(result.current.focusedSeriesIndex).toBeNull();
-		});
-
-		it('drops the focus when the focused slice is hidden', () => {
-			const { result } = renderHook(() => usePieInteractions(DATA));
-
-			act(() =>
-				result.current.onLegendAction({ type: LegendAction.HOVER, seriesIndex: 1 }),
-			);
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.TOGGLE,
-					seriesIndex: 1,
-				}),
-			);
-
-			// Otherwise every remaining arc stays dimmed and the donut reads as an
-			// isolation instead of one slice being excluded.
+			act(() => result.current.onLegendMouseLeave());
 			expect(result.current.active).toBeNull();
 			expect(result.current.focusedSeriesIndex).toBeNull();
 		});
@@ -193,15 +115,8 @@ describe('usePieInteractions', () => {
 		it('does not focus a hidden slice', () => {
 			const { result } = renderHook(() => usePieInteractions(DATA));
 
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.TOGGLE,
-					seriesIndex: 1,
-				}),
-			);
-			act(() =>
-				result.current.onLegendAction({ type: LegendAction.HOVER, seriesIndex: 1 }),
-			);
+			act(() => result.current.onLegendClick(legendEvent(1, true))); // hide cart
+			act(() => result.current.onLegendMouseMove(legendEvent(1)));
 
 			expect(result.current.active).toBeNull();
 		});
@@ -210,12 +125,7 @@ describe('usePieInteractions', () => {
 	describe('persistence', () => {
 		it('does not write to storage when no id is provided', () => {
 			const { result } = renderHook(() => usePieInteractions(DATA));
-			act(() =>
-				result.current.onLegendAction({
-					type: LegendAction.TOGGLE,
-					seriesIndex: 0,
-				}),
-			);
+			act(() => result.current.onLegendClick(legendEvent(0, true)));
 			expect(mockUpdateStored).not.toHaveBeenCalled();
 		});
 

frontend/src/lib/visualization/hooks/usePieInteractions.ts

@@ -1,11 +1,6 @@
 import { LegendItem } from 'lib/uPlotV2/config/types';
-import {
-	LegendAction,
-	LegendActionPayload,
-	OnLegendAction,
-} from 'lib/uPlotV2/components/types';
-import type { Dispatch, SetStateAction } from 'react';
-import { useCallback, useEffect, useMemo, useState } from 'react';
+import type { Dispatch, MouseEvent, SetStateAction } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import {
 	getStoredSeriesVisibility,
@@ -23,15 +18,27 @@ export interface UsePieInteractionsResult {
 	legendItems: LegendItem[];
 	/** Index of the active slice for the legend's focus highlight, or null. */
 	focusedSeriesIndex: number | null;
-	/** Every legend interaction, dispatched by type. */
-	onLegendAction: OnLegendAction;
+	onLegendClick: (e: MouseEvent<HTMLDivElement>) => void;
+	onLegendMouseMove: (e: MouseEvent<HTMLDivElement>) => void;
+	onLegendMouseLeave: () => void;
+}
+
+// Reads the slice index off the nearest `[data-legend-item-id]` ancestor of the
+// event target (the shared Legend tags each item with its seriesIndex).
+function getLegendIndex(e: MouseEvent<HTMLDivElement>): number | null {
+	const el = (e.target as HTMLElement | null)?.closest<HTMLElement>(
+		'[data-legend-item-id]',
+	);
+	const id = el?.dataset.legendItemId;
+	return id != null ? Number(id) : null;
 }
 
 /**
- * Pie interaction + derived state: hover/focus, slice hide/show driven by the
- * shared legend's actions, and persistence of the hidden set to localStorage
- * (keyed by `id`, matched by label) so it survives reloads. Returns the visible
- * slices, legend items, focus index, and the legend action dispatch.
+ * Pie interaction + derived state: hover/focus, slice hide/unhide (mirroring the
+ * uPlot legend — marker toggles one, label isolates), and persistence of the
+ * hidden set to localStorage (keyed by `id`, matched by label) so it survives
+ * reloads. Returns the visible slices, legend items, focus index, and the
+ * legend container handlers.
  */
 export function usePieInteractions(
 	data: PieSlice[],
@@ -41,6 +48,7 @@ export function usePieInteractions(
 	const [hiddenIndices, setHiddenIndices] = useState<Set<number>>(
 		() => new Set(),
 	);
+	const isolatedIndexRef = useRef<number | null>(null);
 
 	const legendItems = useMemo<LegendItem[]>(
 		() =>
@@ -96,88 +104,65 @@ export function usePieInteractions(
 		[id, data],
 	);
 
-	const hoverSeries = useCallback(
-		(sliceIndex: number | null): void => {
+	const onLegendMouseMove = useCallback(
+		(e: MouseEvent<HTMLDivElement>): void => {
+			const index = getLegendIndex(e);
 			// Don't focus/dim for hidden slices — they aren't on the donut.
-			setActive(
-				sliceIndex != null && !hiddenIndices.has(sliceIndex)
-					? data[sliceIndex]
-					: null,
-			);
+			setActive(index != null && !hiddenIndices.has(index) ? data[index] : null);
 		},
 		[data, hiddenIndices],
 	);
 
-	const toggleSeries = useCallback(
-		(sliceIndex: number): void => {
-			const next = new Set(hiddenIndices);
-			if (next.has(sliceIndex)) {
-				next.delete(sliceIndex);
-			} else {
-				// An empty donut is never worth reaching.
-				if (data.length - next.size <= 1) {
-					return;
-				}
-				next.add(sliceIndex);
+	// Marker click toggles just that slice on/off; label click isolates it
+	// (clicking the isolated one again resets to all) — mirrors the uPlot legend.
+	const onLegendClick = useCallback(
+		(e: MouseEvent<HTMLDivElement>): void => {
+			const index = getLegendIndex(e);
+			if (index == null) {
+				return;
 			}
-			applyHidden(next);
-		},
-		[data.length, hiddenIndices, applyHidden],
-	);
+			const isMarker = (e.target as HTMLElement).dataset.isLegendMarker;
 
-	const showOnlySeries = useCallback(
-		(sliceIndex: number): void => {
-			const next = new Set<number>();
-			data.forEach((_, index) => {
-				if (index !== sliceIndex) {
+			if (isMarker) {
+				const next = new Set(hiddenIndices);
+				if (next.has(index)) {
+					next.delete(index);
+				} else {
 					next.add(index);
 				}
+				applyHidden(next);
+				return;
+			}
+
+			const isReset = isolatedIndexRef.current === index;
+			isolatedIndexRef.current = isReset ? null : index;
+			if (isReset) {
+				applyHidden(new Set());
+				return;
+			}
+			const next = new Set<number>();
+			data.forEach((_, i) => {
+				if (i !== index) {
+					next.add(i);
+				}
 			});
 			applyHidden(next);
 		},
-		[data, applyHidden],
+		[data, hiddenIndices, applyHidden],
 	);
 
-	const showAllSeries = useCallback(
-		(): void => applyHidden(new Set()),
-		[applyHidden],
-	);
+	const onLegendMouseLeave = useCallback((): void => setActive(null), []);
 
-	const onLegendAction = useCallback(
-		(payload: LegendActionPayload): void => {
-			switch (payload.type) {
-				case LegendAction.TOGGLE:
-					toggleSeries(payload.seriesIndex);
-					break;
-				case LegendAction.SHOW_ONLY:
-					showOnlySeries(payload.seriesIndex);
-					break;
-				case LegendAction.SHOW_ALL:
-					showAllSeries();
-					break;
-				case LegendAction.HOVER:
-					hoverSeries(payload.seriesIndex);
-					break;
-				default:
-					break;
-			}
-		},
-		[toggleSeries, showOnlySeries, showAllSeries, hoverSeries],
-	);
-
-	const activeIndex = active ? data.indexOf(active) : -1;
-	// Left active, a hidden slice keeps every other arc dimmed, which reads as an
-	// isolation rather than as one slice being excluded.
-	const effectiveActive =
-		activeIndex >= 0 && !hiddenIndices.has(activeIndex) ? active : null;
-	const focusedIndex = effectiveActive ? activeIndex : -1;
+	const focusedIndex = active ? data.indexOf(active) : -1;
 
 	return {
-		active: effectiveActive,
+		active,
 		setActive,
 		visibleData,
 		legendItems,
 		focusedSeriesIndex: focusedIndex >= 0 ? focusedIndex : null,
-		onLegendAction,
+		onLegendClick,
+		onLegendMouseMove,
+		onLegendMouseLeave,
 	};
 }

frontend/src/lib/visualization/layout/ChartLayout/ChartLayout.styles.scss

@@ -29,6 +29,7 @@
 		box-sizing: border-box;
 		min-height: 0;
 		overflow: hidden;
-		padding: 0 12px 12px 12px;
+		padding-left: 12px;
+		padding-bottom: 12px;
 	}
 }

frontend/src/lib/visualization/layout/ChartLayout/ChartLayout.tsx

@@ -1,7 +1,7 @@
 import { useMemo } from 'react';
 import cx from 'classnames';
 import { calculateChartDimensions } from 'lib/visualization/charts/utils';
-import { MAX_LEGEND_WIDTH } from 'lib/uPlotV2/components/Legend/constants';
+import { MAX_LEGEND_WIDTH } from 'lib/uPlotV2/components/Legend/Legend';
 import { LegendConfig, LegendPosition } from 'lib/uPlotV2/components/types';
 import { UPlotConfigBuilder } from 'lib/uPlotV2/config/UPlotConfigBuilder';
 
@@ -16,20 +16,31 @@ export interface ChartLayoutProps {
 		averageLegendWidth: number;
 	}) => React.ReactNode;
 	layoutChildren?: React.ReactNode;
+	/**
+	 * Rendered directly under the plot, inside the chart column — so it stays next to
+	 * the axis with the legend below it, and beside a RIGHT legend rather than under
+	 * it. `layoutChildren` sits below everything instead.
+	 */
+	contentFooter?: React.ReactNode;
 	containerWidth: number;
 	containerHeight: number;
 	legendConfig: LegendConfig;
 	config: UPlotConfigBuilder;
+	/** Defaults to the chart's series labels. Pass them when the legend lists
+	 *  something else, or the split is measured against the wrong text. */
+	seriesLabels?: string[];
 }
 export default function ChartLayout({
 	showLegend = true,
 	legendComponent,
 	children,
 	layoutChildren,
+	contentFooter,
 	containerWidth,
 	containerHeight,
 	legendConfig,
 	config,
+	seriesLabels,
 }: ChartLayoutProps): JSX.Element {
 	const chartDimensions = useMemo(
 		() => {
@@ -42,19 +53,20 @@ export default function ChartLayout({
 					averageLegendWidth: MAX_LEGEND_WIDTH,
 				};
 			}
-			const legendItemsMap = config.getLegendItems();
-			const seriesLabels = Object.values(legendItemsMap)
-				.map((item) => item.label)
-				.filter((label): label is string => label !== undefined);
+			const resolvedLabels =
+				seriesLabels ??
+				Object.values(config.getLegendItems())
+					.map((item) => item.label)
+					.filter((label): label is string => label !== undefined);
 			return calculateChartDimensions({
 				containerWidth,
 				containerHeight,
 				legendConfig,
-				seriesLabels,
+				seriesLabels: resolvedLabels,
 			});
 		},
 		// eslint-disable-next-line react-hooks/exhaustive-deps
-		[containerWidth, containerHeight, legendConfig, showLegend],
+		[containerWidth, containerHeight, legendConfig, showLegend, seriesLabels],
 	);
 
 	return (
@@ -72,6 +84,7 @@ export default function ChartLayout({
 						chartHeight: chartDimensions.height,
 						averageLegendWidth: chartDimensions.averageLegendWidth,
 					})}
+					{contentFooter}
 				</div>
 				{showLegend && (
 					<div

frontend/src/pages/DashboardPage/DashboardContainer/DashboardSettings/Variables/VariableImpactDialog/VariableImpactDialog.tsx

@@ -19,7 +19,6 @@ const KIND_LABEL: Record<VariableUsage['kind'], string> = {
 	promql: 'PromQL',
 	clickhouse: 'ClickHouse',
 	variable: 'Variable',
-	text: 'Markdown body',
 };
 
 interface VariableImpactDialogProps {

frontend/src/pages/DashboardPage/DashboardContainer/DashboardSettings/Variables/__tests__/variableImpactPatch.test.ts

@@ -1,49 +0,0 @@
-import type { DashboardtypesGettableDashboardV2DTO } from 'api/generated/services/sigNoz.schemas';
-
-import { buildVariableImpactPatch } from '../utils/variableImpactPatch';
-import type { VariableUsage } from '../utils/variableUsages';
-
-jest.mock('../variableAdapters', () => ({
-	formModelToDto: (model: unknown): unknown => model,
-}));
-
-const dashboard = {
-	spec: {
-		panels: {
-			runbook: {
-				spec: {
-					display: { name: 'Runbook' },
-					plugin: { kind: 'signoz/TextPanel', spec: { text: 'env {{svc}}' } },
-					queries: [],
-				},
-			},
-		},
-		variables: [],
-	},
-} as unknown as DashboardtypesGettableDashboardV2DTO;
-
-const textUsage: VariableUsage = {
-	id: 'panel:runbook:0',
-	sourceType: 'panel',
-	sourceId: 'runbook',
-	sourceLabel: 'Runbook',
-	kind: 'text',
-	envelopeIndex: 0,
-	currentText: 'env {{svc}}',
-	resultingText: 'env {{zone}}',
-};
-
-describe('buildVariableImpactPatch — text panel bodies', () => {
-	it('replaces the plugin-spec text, never the (empty) queries', () => {
-		const ops = buildVariableImpactPatch(dashboard, [], [textUsage]);
-
-		const panelOps = ops.filter((op) => op.path.includes('/panels/'));
-		expect(panelOps).toStrictEqual([
-			{
-				op: 'replace',
-				path: '/spec/panels/runbook/spec/plugin/spec/text',
-				value: 'env {{zone}}',
-			},
-		]);
-	});
-});

frontend/src/pages/DashboardPage/DashboardContainer/DashboardSettings/Variables/__tests__/variableUsages.test.ts

@@ -45,16 +45,6 @@ function promqlPanel(name: string, query: string): unknown {
 	};
 }
 
-function textPanel(name: string, text: string): unknown {
-	return {
-		spec: {
-			display: { name },
-			plugin: { kind: 'signoz/TextPanel', spec: { text } },
-			queries: [],
-		},
-	};
-}
-
 function dashboard(
 	panels: Record<string, unknown>,
 	variables: VariableFormModel[],
@@ -109,38 +99,6 @@ describe('findVariableUsages', () => {
 	it('returns nothing for an unreferenced variable', () => {
 		expect(findVariableUsages(dash, 'nope', 'delete')).toStrictEqual([]);
 	});
-
-	describe('text panel bodies (TDD D5)', () => {
-		const textDash = dashboard(
-			{
-				runbook: textPanel(
-					'Runbook',
-					'env {{svc}} / {{.svc}} / [[svc]] / $svc / {{svcx}}',
-				),
-				unrelated: textPanel('Plain', 'no tokens here'),
-			},
-			[variable({ name: 'svc', type: 'QUERY' })],
-		);
-
-		it('finds the body usage and skips bodies without the token', () => {
-			const usages = findVariableUsages(textDash, 'svc', 'rename', 'zone');
-			expect(usages.map((u) => u.id)).toStrictEqual(['panel:runbook:0']);
-			expect(usages[0].kind).toBe('text');
-			expect(usages[0].sourceLabel).toBe('Runbook');
-		});
-
-		it('rewrites all four syntaxes on rename, leaving other names alone', () => {
-			const [usage] = findVariableUsages(textDash, 'svc', 'rename', 'zone');
-			expect(usage.resultingText).toBe(
-				'env {{zone}} / {{.zone}} / [[zone]] / $zone / {{svcx}}',
-			);
-		});
-
-		it('leaves the body for review on delete', () => {
-			const [usage] = findVariableUsages(textDash, 'svc', 'delete');
-			expect(usage.resultingText).toBe(usage.currentText);
-		});
-	});
 });
 
 describe('findApplyUsages', () => {

frontend/src/pages/DashboardPage/DashboardContainer/DashboardSettings/Variables/utils/getTextPanelBody.ts

@@ -1,16 +0,0 @@
-import type { DashboardtypesPanelSpecDTO } from 'api/generated/services/sigNoz.schemas';
-import { isStaticPanelKind } from 'pages/DashboardPage/DashboardContainer/Panels/capabilities';
-
-/**
- * The markdown body of a static (query-less) panel, or null for query kinds.
- * One localized cast: the plugin-spec union can't be narrowed by a dynamic kind.
- */
-export function getTextPanelBody(
-	spec: DashboardtypesPanelSpecDTO | undefined,
-): string | null {
-	if (!spec?.plugin || !isStaticPanelKind(spec.plugin.kind)) {
-		return null;
-	}
-	const { text } = spec.plugin.spec as { text?: string };
-	return typeof text === 'string' ? text : null;
-}

frontend/src/pages/DashboardPage/DashboardContainer/DashboardSettings/Variables/utils/variableImpactPatch.ts

@@ -107,18 +107,6 @@ export function buildVariableImpactPatch(
 
 	byPanel.forEach((list, panelId) => {
 		const panel = panels[panelId];
-
-		// A static kind's usage edits its markdown body, not a query.
-		const textUsage = list.find((usage) => usage.kind === 'text');
-		if (textUsage) {
-			ops.push({
-				op: 'replace' as DashboardtypesJSONPatchOperationDTO['op'],
-				path: `/spec/panels/${panelId}/spec/plugin/spec/text`,
-				value: textUsage.resultingText,
-			});
-			return;
-		}
-
 		if (!panel?.spec?.queries?.length) {
 			return;
 		}

frontend/src/pages/DashboardPage/DashboardContainer/DashboardSettings/Variables/utils/variableUsages.ts

@@ -12,7 +12,6 @@ import {
 } from 'lib/dashboardVariables/variableReference';
 
 import { toQueryEnvelopes } from '../../../queryV5/buildQueryRangeRequest';
-import { getTextPanelBody } from './getTextPanelBody';
 import { dtoToFormModel } from '../variableAdapters';
 
 /** The kind of query text a variable is referenced from. */
@@ -20,8 +19,7 @@ export type VariableUsageKind =
 	| 'builder'
 	| 'promql'
 	| 'clickhouse'
-	| 'variable'
-	| 'text';
+	| 'variable';
 
 export type VariableImpactMode = 'rename' | 'delete' | 'apply';
 
@@ -83,7 +81,7 @@ function computeResultingText(
 		return rewriteVariableReferences(text, variableName, newName);
 	}
 	// delete: only builder filter clauses can be safely auto-stripped; raw PromQL/
-	// ClickHouse, markdown bodies and variable queries are left for the user to edit.
+	// ClickHouse and variable queries are left for the user to edit.
 	return kind === 'builder'
 		? removeVariableFromExpression(text, variableName)
 		: text;
@@ -108,31 +106,6 @@ export function findVariableUsages(
 	const spec = dashboard.spec;
 
 	Object.entries(spec.panels ?? {}).forEach(([panelId, panel]) => {
-		// A static kind references variables from its body, not a query (TDD D5 —
-		// rename must rewrite text bodies too, or it silently orphans the tokens).
-		const textBody = getTextPanelBody(panel?.spec);
-		if (typeof textBody === 'string') {
-			if (textContainsVariableReference(textBody, variableName)) {
-				usages.push({
-					id: `panel:${panelId}:0`,
-					sourceType: 'panel',
-					sourceId: panelId,
-					sourceLabel: panel.spec?.display?.name || panelId,
-					kind: 'text',
-					envelopeIndex: 0,
-					currentText: textBody,
-					resultingText: computeResultingText(
-						'text',
-						textBody,
-						variableName,
-						mode,
-						newName,
-					),
-				});
-			}
-			return;
-		}
-
 		const queries = panel?.spec?.queries;
 		if (!queries?.length) {
 			return;

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/ConfigPane.tsx

@@ -5,7 +5,6 @@ import type {
 	DashboardtypesPanelSpecDTO,
 } from 'api/generated/services/sigNoz.schemas';
 import { getPanelDefinition } from 'pages/DashboardPage/DashboardContainer/Panels/registry';
-import { SectionKind } from 'pages/DashboardPage/DashboardContainer/Panels/types/sections';
 import { getSupportedSignals } from 'pages/DashboardPage/DashboardContainer/Panels/capabilities';
 import { resolveSignal } from 'pages/DashboardPage/DashboardContainer/Panels/utils/getBuilderQueries';
 import type { EQueryType } from 'types/common/dashboard';
@@ -67,14 +66,7 @@ function ConfigPane({
 }: ConfigPaneProps): JSX.Element {
 	const panelKind = spec.plugin.kind;
 	const definition = getPanelDefinition(panelKind);
-	// The header toggle belongs with the title and description it hides, so the kind's
-	// declaration still gates it but it renders above, out of the display options.
-	const headerSection = definition.sections.find(
-		(config) => config.kind === SectionKind.PanelHeader,
-	);
-	const sections = definition.sections.filter(
-		(config) => config.kind !== SectionKind.PanelHeader,
-	);
+	const sections = definition.sections;
 
 	const signal = resolveSignal(spec.queries, getSupportedSignals(panelKind)[0]);
 
@@ -113,23 +105,6 @@ function ConfigPane({
 						onChange={(e): void => setDisplayField('description', e.target.value)}
 					/>
 				</div>
-
-				{headerSection && (
-					<SectionSlot
-						bare
-						config={headerSection}
-						spec={spec}
-						onChangeSpec={onChangeSpec}
-						legendSeries={legendSeries}
-						tableColumns={tableColumns}
-						signal={signal}
-						panelKind={panelKind}
-						onChangePanelKind={onChangePanelKind}
-						queryType={queryType}
-						stepInterval={stepInterval}
-						metricUnit={metricUnit}
-					/>
-				)}
 			</div>
 
 			{sections.length > 0 && (

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/PanelTypeSwitcher/utils.ts

@@ -2,7 +2,6 @@ import { TelemetrytypesSignalDTO } from 'api/generated/services/sigNoz.schemas';
 import { EQueryType } from 'types/common/dashboard';
 
 import {
-	isStaticPanelKind,
 	isQueryTypeSupportedByPanelKind,
 	isSignalSupported,
 } from '../../../Panels/capabilities';
@@ -38,12 +37,6 @@ export function getPanelTypeDisabledReason({
 	signal?: TelemetrytypesSignalDTO;
 	label: string;
 }): string | undefined {
-	// A kind that renders without a query pairs with anything — it declares no
-	// query types or signals, and the checks below would read that as "supports
-	// nothing" and disable it everywhere.
-	if (isStaticPanelKind(kind)) {
-		return undefined;
-	}
 	if (!isQueryTypeSupportedByPanelKind(kind, queryType)) {
 		return `${label} isn't available for ${QUERY_TYPE_LABEL[queryType]} queries`;
 	}

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/SectionSlot/SectionSlot.tsx

@@ -16,8 +16,6 @@ type SectionSlotProps = {
 	config: SectionConfig;
 	spec: DashboardtypesPanelSpecDTO;
 	onChangeSpec: (next: DashboardtypesPanelSpecDTO) => void;
-	/** Renders the editor alone, for a section promoted into the Panel Details fields. */
-	bare?: boolean;
 } & Omit<SectionEditorContext, 'yAxisUnit' | 'registerHeaderAction'>;
 
 // Per-section header content; `trigger` expands the section and runs the editor's handler.
@@ -52,7 +50,6 @@ function SectionSlot({
 	config,
 	spec,
 	onChangeSpec,
-	bare,
 	legendSeries,
 	tableColumns,
 	signal,
@@ -113,28 +110,6 @@ function SectionSlot({
 
 	const headerSlot = SECTION_HEADER_SLOT[config.kind]?.(triggerHeaderAction);
 
-	const editorElement = (
-		<Component
-			value={get(spec)}
-			controls={controls}
-			onChange={(next): void => onChangeSpec(update(spec, next))}
-			legendSeries={legendSeries}
-			yAxisUnit={yAxisUnit}
-			tableColumns={tableColumns}
-			signal={signal}
-			panelKind={panelKind}
-			onChangePanelKind={onChangePanelKind}
-			queryType={queryType}
-			stepInterval={stepInterval}
-			metricUnit={metricUnit}
-			registerHeaderAction={registerHeaderAction}
-		/>
-	);
-
-	if (bare) {
-		return editorElement;
-	}
-
 	return (
 		<SettingsSection
 			title={title}
@@ -143,7 +118,21 @@ function SectionSlot({
 			onOpenChange={setOpen}
 			headerSlot={headerSlot}
 		>
-			{editorElement}
+			<Component
+				value={get(spec)}
+				controls={controls}
+				onChange={(next): void => onChangeSpec(update(spec, next))}
+				legendSeries={legendSeries}
+				yAxisUnit={yAxisUnit}
+				tableColumns={tableColumns}
+				signal={signal}
+				panelKind={panelKind}
+				onChangePanelKind={onChangePanelKind}
+				queryType={queryType}
+				stepInterval={stepInterval}
+				metricUnit={metricUnit}
+				registerHeaderAction={registerHeaderAction}
+			/>
 		</SettingsSection>
 	);
 }

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/__tests__/ConfigPane.test.tsx

@@ -23,14 +23,6 @@ jest.mock(
 	}),
 );
 
-function textSpec(): DashboardtypesPanelSpecDTO {
-	return {
-		display: { name: 'Runbook', description: 'steps' },
-		plugin: { kind: 'signoz/TextPanel', spec: { text: '' } },
-		queries: [],
-	} as unknown as DashboardtypesPanelSpecDTO;
-}
-
 function spec(unit?: string): DashboardtypesPanelSpecDTO {
 	return {
 		display: { name: 'CPU', description: 'usage' },
@@ -101,24 +93,6 @@ describe('ConfigPane', () => {
 		);
 	});
 
-	// It hides the title strip, so it sits with the title rather than under the
-	// display options — and only a kind whose spec accepts `headerOptions` shows it.
-	it('renders the hide-header toggle among the Panel Details fields', () => {
-		renderConfigPane({ spec: textSpec() });
-
-		const toggle = screen.getByTestId('panel-header-hide');
-		expect(toggle).toBeInTheDocument();
-		expect(screen.getByText('Hide header')).toBeInTheDocument();
-		// No collapsible wrapper of its own.
-		expect(screen.queryByText('Panel header')).not.toBeInTheDocument();
-	});
-
-	it('omits the hide-header toggle for a kind that has no header options', () => {
-		renderConfigPane();
-
-		expect(screen.queryByTestId('panel-header-hide')).not.toBeInTheDocument();
-	});
-
 	it('renders the Formatting section for a kind that declares it', () => {
 		renderConfigPane();
 		// The TimeSeries kind declares a Formatting section; its collapsible header shows.

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/controls/BackgroundSwatches/BackgroundSwatches.module.scss

@@ -1,76 +0,0 @@
-.row {
-	display: flex;
-	align-items: center;
-	gap: 6px;
-}
-
-.swatch {
-	flex: none;
-	width: 26px;
-	height: 26px;
-	padding: 0;
-	display: inline-flex;
-	align-items: center;
-	justify-content: center;
-	border: 1px solid var(--l2-border);
-	border-radius: 4px;
-	background: none;
-	cursor: pointer;
-	position: relative;
-
-	// The input carries focus, so the ring is drawn on the swatch around it.
-	&:has(.input:focus-visible) {
-		outline: 2px solid var(--bg-robin-400);
-		outline-offset: 1px;
-	}
-}
-
-// The real control, sized to the swatch and invisible over it: clicks and focus
-// land on the radio, the swatch is what the user sees.
-.input {
-	position: absolute;
-	inset: 0;
-	margin: 0;
-	opacity: 0;
-	cursor: pointer;
-}
-
-.selected {
-	box-shadow: 0 0 0 2px var(--bg-robin-500);
-}
-
-// Transparency has no colour to show, so it reads as the conventional checkerboard.
-.checkerboard {
-	background-color: var(--l2-background);
-	background-image:
-		linear-gradient(
-			45deg,
-			var(--l2-border) 25%,
-			transparent 25%,
-			transparent 75%,
-			var(--l2-border) 75%
-		),
-		linear-gradient(
-			45deg,
-			var(--l2-border) 25%,
-			transparent 25%,
-			transparent 75%,
-			var(--l2-border) 75%
-		);
-	background-size: 8px 8px;
-	background-position:
-		0 0,
-		4px 4px;
-}
-
-.defaultSurface {
-	background: var(--l2-background);
-}
-
-.divider {
-	flex: none;
-	width: 1px;
-	height: 18px;
-	margin: 0 2px;
-	background: var(--l2-border);
-}

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/controls/BackgroundSwatches/BackgroundSwatches.tsx

@@ -1,119 +0,0 @@
-import { Fragment } from 'react';
-import { Check } from '@signozhq/icons';
-import { TooltipSimple } from '@signozhq/ui/tooltip';
-import cx from 'classnames';
-import {
-	TEXT_BACKGROUND_PAIRS,
-	TEXT_BACKGROUND_PRESETS,
-} from 'pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/background/presets';
-import type {
-	PanelTheme,
-	TextBackgroundPreset,
-	TextBackgroundSelection,
-} from 'pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/background/types';
-import { TextBackgroundKind } from 'pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/background/types';
-
-import styles from './BackgroundSwatches.module.scss';
-
-const PRESET_TITLES: Record<TextBackgroundPreset, string> = {
-	robin: 'Robin',
-	purple: 'Purple',
-	sakura: 'Sakura',
-	cherry: 'Cherry',
-	amber: 'Amber',
-	forest: 'Forest',
-	sienna: 'Sienna',
-	slate: 'Slate',
-};
-
-type BaseSelection = TextBackgroundKind.None | TextBackgroundKind.Default;
-
-const BASE_TITLES: Record<BaseSelection, string> = {
-	none: 'Transparent',
-	default: 'Default panel',
-};
-
-/** Neither base swatch shows a colour, so its tooltip says what it does. */
-const BASE_TOOLTIPS: Record<BaseSelection, string> = {
-	none: 'Transparent — no card, border or title bar',
-	default: 'Default panel colour',
-};
-
-const OPTIONS: TextBackgroundSelection[] = [
-	TextBackgroundKind.None,
-	TextBackgroundKind.Default,
-	...TEXT_BACKGROUND_PRESETS,
-];
-
-const DIVIDER_AFTER = 1;
-
-interface BackgroundSwatchesProps {
-	testId: string;
-	/** Names the group for assistive tech — the row carries no visible label. */
-	label: string;
-	/** `undefined` while a custom colour is active: no swatch is selected. */
-	value: TextBackgroundSelection | undefined;
-	/** Swatches paint in this theme's pair, so what the user picks is what they see. */
-	theme: PanelTheme;
-	onChange: (value: TextBackgroundSelection) => void;
-}
-
-/**
- * The Text panel's background choices as one radio group. Native radios sharing a
- * `name`, so arrow-key movement, the single tab stop and selection-follows-focus
- * are the platform's; each input is transparent and fills its swatch.
- */
-function BackgroundSwatches({
-	testId,
-	label,
-	value,
-	theme,
-	onChange,
-}: BackgroundSwatchesProps): JSX.Element {
-	return (
-		<div
-			className={styles.row}
-			role="radiogroup"
-			aria-label={label}
-			data-testid={testId}
-		>
-			{OPTIONS.map((option, index) => {
-				const isBase =
-					option === TextBackgroundKind.None ||
-					option === TextBackgroundKind.Default;
-				const pair = isBase ? undefined : TEXT_BACKGROUND_PAIRS[option][theme];
-				const title = isBase ? BASE_TITLES[option] : PRESET_TITLES[option];
-
-				return (
-					<Fragment key={option}>
-						<TooltipSimple title={isBase ? BASE_TOOLTIPS[option] : title} arrow>
-							<label
-								className={cx(styles.swatch, {
-									[styles.checkerboard]: option === TextBackgroundKind.None,
-									[styles.defaultSurface]: option === TextBackgroundKind.Default,
-									[styles.selected]: option === value,
-								})}
-								style={pair ? { background: pair.surface, color: pair.ink } : undefined}
-								data-testid={`${testId}-${option}`}
-							>
-								<input
-									type="radio"
-									className={styles.input}
-									name={testId}
-									value={option}
-									checked={option === value}
-									aria-label={title}
-									onChange={(): void => onChange(option)}
-								/>
-								{option === value && <Check size={14} />}
-							</label>
-						</TooltipSimple>
-						{index === DIVIDER_AFTER && <span className={styles.divider} />}
-					</Fragment>
-				);
-			})}
-		</div>
-	);
-}
-
-export default BackgroundSwatches;

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/controls/BackgroundSwatches/CustomBackgroundRow.module.scss

@@ -1,67 +0,0 @@
-.row {
-	display: flex;
-	width: 100%;
-	align-items: center;
-	gap: 10px;
-	padding: 8px 10px;
-	border: 1px solid var(--l2-border);
-	border-radius: 4px;
-	background: transparent;
-	cursor: pointer;
-	text-align: left;
-}
-
-.active {
-	border-color: var(--bg-robin-500);
-}
-
-.chip {
-	flex: none;
-	width: 18px;
-	height: 18px;
-	display: inline-flex;
-	align-items: center;
-	justify-content: center;
-	border: 1px solid var(--l2-border);
-	border-radius: 4px;
-}
-
-// No colour to show yet, so the chip advertises that it opens a picker.
-.chipEmpty {
-	background: conic-gradient(
-		from 0deg,
-		var(--bg-cherry-400),
-		var(--bg-amber-400),
-		var(--bg-forest-400),
-		var(--bg-robin-400),
-		var(--bg-sakura-400),
-		var(--bg-cherry-400)
-	);
-}
-
-.label {
-	flex: 1;
-	font-size: 12px;
-	color: var(--l2-foreground);
-}
-
-.hex {
-	font-family: var(--font-family-sf-mono);
-	font-size: 12px;
-	color: var(--text-vanilla-400);
-	letter-spacing: 0.02em;
-}
-
-// Appended under the picker's own panel.
-.contrast {
-	display: flex;
-	align-items: center;
-	gap: 6px;
-	padding: 8px 4px 2px;
-	font-size: 12px;
-	color: var(--text-vanilla-400);
-}
-
-.warning {
-	color: var(--bg-amber-400);
-}

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/controls/BackgroundSwatches/CustomBackgroundRow.tsx

@@ -1,91 +0,0 @@
-import type { ReactNode } from 'react';
-import { Check, ChevronDown, TriangleAlert } from '@signozhq/icons';
-import { Typography } from '@signozhq/ui/typography';
-import { ColorPicker } from 'antd';
-import cx from 'classnames';
-import {
-	contrastRatio,
-	inkForSurface,
-	MIN_CONTRAST_RATIO,
-} from 'pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/background/contrast';
-
-import styles from './CustomBackgroundRow.module.scss';
-
-const HEX_PLACEHOLDER = '#______';
-
-/** What the picker opens on before a colour is chosen. */
-const INITIAL_COLOR = '#3A2A63';
-
-interface CustomBackgroundRowProps {
-	testId: string;
-	/** The stored hex while a custom colour is active; `undefined` otherwise. */
-	value: string | undefined;
-	onChange: (hex: string) => void;
-}
-
-/**
- * The custom colour, as a row rather than a swatch: it opens a picker instead of
- * committing a value in one click. The picker warns below the contrast floor but
- * never blocks the choice.
- */
-function CustomBackgroundRow({
-	testId,
-	value,
-	onChange,
-}: CustomBackgroundRowProps): JSX.Element {
-	const color = value ?? INITIAL_COLOR;
-	const ratio = contrastRatio(inkForSurface(color), color);
-	const isLegible = ratio >= MIN_CONTRAST_RATIO;
-
-	const contrastMessage = isLegible
-		? `Contrast ${ratio.toFixed(1)}:1`
-		: `Contrast ${ratio.toFixed(1)}:1 — below ${MIN_CONTRAST_RATIO}:1`;
-
-	function renderPanel(panel: ReactNode): ReactNode {
-		return (
-			<>
-				{panel}
-				<div
-					className={cx(styles.contrast, { [styles.warning]: !isLegible })}
-					data-testid={`${testId}-contrast`}
-				>
-					{!isLegible && <TriangleAlert size={12} />}
-					<span className="translate-safe">{contrastMessage}</span>
-				</div>
-			</>
-		);
-	}
-
-	return (
-		<ColorPicker
-			value={color}
-			size="small"
-			showText={false}
-			trigger="click"
-			panelRender={renderPanel}
-			onChangeComplete={(next): void => onChange(next.toHexString())}
-		>
-			<button
-				type="button"
-				className={cx(styles.row, { [styles.active]: value !== undefined })}
-				data-testid={testId}
-			>
-				<span
-					className={cx(styles.chip, { [styles.chipEmpty]: value === undefined })}
-					style={
-						value ? { background: value, color: inkForSurface(value) } : undefined
-					}
-				>
-					{value !== undefined && <Check size={14} />}
-				</span>
-				<Typography.Text className={styles.label}>Custom</Typography.Text>
-				<span className={cx(styles.hex, 'translate-safe')}>
-					{value ?? HEX_PLACEHOLDER}
-				</span>
-				<ChevronDown size={14} />
-			</button>
-		</ColorPicker>
-	);
-}
-
-export default CustomBackgroundRow;

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/controls/BackgroundSwatches/__tests__/BackgroundSwatches.test.tsx

@@ -1,118 +0,0 @@
-import { fireEvent, render, screen, waitFor } from '@testing-library/react';
-import { TooltipProvider } from '@signozhq/ui/tooltip';
-import { TEXT_BACKGROUND_PAIRS } from 'pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/background/presets';
-import {
-	PanelTheme,
-	TextBackgroundKind,
-	TextBackgroundPreset,
-} from 'pages/DashboardPage/DashboardContainer/Panels/kinds/TextPanel/background/types';
-
-import BackgroundSwatches from '../BackgroundSwatches';
-
-function renderRow(
-	props: Partial<React.ComponentProps<typeof BackgroundSwatches>> = {},
-): jest.Mock {
-	const onChange = jest.fn();
-	render(
-		<TooltipProvider>
-			<BackgroundSwatches
-				testId="background"
-				label="Panel background"
-				theme={PanelTheme.Dark}
-				value={TextBackgroundKind.Default}
-				onChange={onChange}
-				{...props}
-			/>
-		</TooltipProvider>,
-	);
-	return onChange;
-}
-
-describe('BackgroundSwatches', () => {
-	it('offers transparent, the default surface and the eight presets in order', () => {
-		renderRow();
-
-		expect(
-			screen
-				.getAllByRole('radio')
-				.map((swatch) => swatch.getAttribute('aria-label')),
-		).toStrictEqual([
-			'Transparent',
-			'Default panel',
-			'Robin',
-			'Purple',
-			'Sakura',
-			'Cherry',
-			'Amber',
-			'Forest',
-			'Sienna',
-			'Slate',
-		]);
-	});
-
-	it('is one labelled group', () => {
-		renderRow();
-
-		expect(
-			screen.getByRole('radiogroup', { name: 'Panel background' }),
-		).toBeInTheDocument();
-	});
-
-	it.each([
-		['background-none', 'Transparent — no card, border or title bar'],
-		['background-default', 'Default panel colour'],
-		['background-sakura', 'Sakura'],
-	])('explains %s on hover', async (swatchId, copy) => {
-		renderRow();
-
-		fireEvent.focus(screen.getByTestId(swatchId));
-
-		await waitFor(() => {
-			expect(screen.getByRole('tooltip')).toHaveTextContent(copy);
-		});
-	});
-
-	it('paints each preset in the given theme', () => {
-		renderRow({ theme: PanelTheme.Light });
-
-		expect(screen.getByTestId('background-amber')).toHaveStyle({
-			background: TEXT_BACKGROUND_PAIRS.amber.light.surface,
-			color: TEXT_BACKGROUND_PAIRS.amber.light.ink,
-		});
-	});
-
-	it('marks only the selected swatch, and checks it', () => {
-		renderRow({ value: TextBackgroundPreset.Forest });
-
-		expect(screen.getByRole('radio', { name: 'Forest' })).toBeChecked();
-		expect(
-			screen.getByRole('radio', { name: 'Default panel' }),
-		).not.toBeChecked();
-		expect(
-			screen.getByTestId('background-forest').querySelector('svg'),
-		).toBeInTheDocument();
-		expect(
-			screen.getByTestId('background-default').querySelector('svg'),
-		).not.toBeInTheDocument();
-	});
-
-	it('reports the swatch that was clicked', () => {
-		const onChange = renderRow();
-
-		fireEvent.click(screen.getByRole('radio', { name: 'Sienna' }));
-
-		expect(onChange).toHaveBeenCalledWith('sienna');
-	});
-
-	// jsdom does not implement radio arrow navigation, so the shared name — what
-	// makes them one group — is what there is to assert.
-	it('groups every swatch under one radio name', () => {
-		renderRow();
-
-		const names = new Set(
-			screen.getAllByRole('radio').map((swatch) => swatch.getAttribute('name')),
-		);
-
-		expect(names).toStrictEqual(new Set(['background']));
-	});
-});

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/controls/BackgroundSwatches/__tests__/CustomBackgroundRow.test.tsx

@@ -1,77 +0,0 @@
-import { fireEvent, render, screen } from '@testing-library/react';
-
-import CustomBackgroundRow from '../CustomBackgroundRow';
-
-function renderRow(value?: string): jest.Mock {
-	const onChange = jest.fn();
-	render(
-		<CustomBackgroundRow testId="custom" value={value} onChange={onChange} />,
-	);
-	return onChange;
-}
-
-describe('CustomBackgroundRow', () => {
-	it('stands in for the hex while no custom colour is set', () => {
-		renderRow();
-
-		expect(screen.getByTestId('custom')).toHaveTextContent('#______');
-	});
-
-	it('shows the stored hex once one is set', () => {
-		renderRow('#3A2A63');
-
-		expect(screen.getByTestId('custom')).toHaveTextContent('#3A2A63');
-	});
-
-	it('checks the chip only while the custom colour is the selection', () => {
-		renderRow('#3A2A63');
-
-		expect(screen.getByTestId('custom').querySelector('svg')).toBeInTheDocument();
-	});
-
-	it('leaves the chip unchecked while no custom colour is set', () => {
-		renderRow();
-
-		expect(screen.getByTestId('custom').querySelectorAll('svg')).toHaveLength(1);
-	});
-
-	describe('the picker', () => {
-		it('opens on the row', () => {
-			renderRow('#3A2A63');
-
-			fireEvent.click(screen.getByTestId('custom'));
-
-			expect(screen.getByTestId('custom-contrast')).toBeInTheDocument();
-		});
-
-		it('reports the contrast the colour achieves', () => {
-			renderRow('#3A2A63');
-
-			fireEvent.click(screen.getByTestId('custom'));
-
-			// The derived ink is pure white, not purple's paired ink.
-			expect(screen.getByTestId('custom-contrast')).toHaveTextContent(
-				'Contrast 12.4:1',
-			);
-		});
-
-		it('warns when no ink clears the floor, without disabling anything', () => {
-			renderRow('#808080');
-
-			fireEvent.click(screen.getByTestId('custom'));
-
-			expect(screen.getByTestId('custom-contrast')).toHaveTextContent(
-				'below 4.5:1',
-			);
-			expect(screen.getByTestId('custom')).toBeEnabled();
-		});
-
-		it('says nothing about the floor when the colour clears it', () => {
-			renderRow('#111111');
-
-			fireEvent.click(screen.getByTestId('custom'));
-
-			expect(screen.getByTestId('custom-contrast')).not.toHaveTextContent('below');
-		});
-	});
-});

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/sectionRegistry.tsx

@@ -23,8 +23,6 @@ import ChartAppearanceSection from './sections/ChartAppearanceSection/ChartAppea
 import ContextLinksSection from './sections/ContextLinksSection/ContextLinksSection';
 import FormattingSection from './sections/FormattingSection/FormattingSection';
 import LegendSection from './sections/LegendSection/LegendSection';
-import PanelHeaderSection from './sections/PanelHeaderSection/PanelHeaderSection';
-import TextLayoutSection from './sections/TextLayoutSection/TextLayoutSection';
 import ThresholdsSection from './sections/ThresholdsSection/ThresholdsSection';
 import VisualizationSection from './sections/VisualizationSection/VisualizationSection';
 
@@ -119,23 +117,6 @@ export const SECTION_REGISTRY: {
 		update: (spec, buckets): PanelSpec =>
 			updatePluginSlice(spec, 'histogramBuckets', buckets),
 	},
-	[SectionKind.TextLayout]: {
-		Component: TextLayoutSection,
-		get: (spec): SectionSpecMap[SectionKind.TextLayout] | undefined =>
-			getPluginSlice<SectionSpecMap[SectionKind.TextLayout]>(spec, 'presentation'),
-		update: (spec, presentation): PanelSpec =>
-			updatePluginSlice(spec, 'presentation', presentation),
-	},
-	[SectionKind.PanelHeader]: {
-		Component: PanelHeaderSection,
-		get: (spec): SectionSpecMap[SectionKind.PanelHeader] | undefined =>
-			getPluginSlice<SectionSpecMap[SectionKind.PanelHeader]>(
-				spec,
-				'headerOptions',
-			),
-		update: (spec, headerOptions): PanelSpec =>
-			updatePluginSlice(spec, 'headerOptions', headerOptions),
-	},
 	[SectionKind.ContextLinks]: {
 		Component: ContextLinksSection,
 		// Panel-level slice (spec.links), not under the plugin spec — no cast needed.

frontend/src/pages/DashboardPage/DashboardContainer/PanelEditor/ConfigPane/sections/PanelHeaderSection/PanelHeaderSection.tsx

@@ -1,24 +0,0 @@
-import type {
-	SectionEditorProps,
-	SectionKind,
-} from 'pages/DashboardPage/DashboardContainer/Panels/types/sections';
-
-import ConfigSwitch from '../../controls/ConfigSwitch/ConfigSwitch';
-
-/** Edits the Text panel's `headerOptions` slice: the panel card's title strip. */
-function PanelHeaderSection({
-	value,
-	onChange,
-}: SectionEditorProps<SectionKind.PanelHeader>): JSX.Element {
-	return (
-		<ConfigSwitch
-			testId="panel-header-hide"
-			title="Hide header"
-			description="Drop the title strip on the dashboard; hovering the panel shows controls for drag and actions."
-			value={value?.hide === true}
-			onChange={(hide): void => onChange({ ...value, hide })}
-		/>
-	);
-}
-
-export default PanelHeaderSection;