Merge branch 'main' of https://github.com/SigNoz/signoz into chore/tooltip-pinning

* chore: added changes for crosshair sync for tooltip

* chore: minor cleanup

* chore: updated the core structure

* chore: updated the types

* chore: minor cleanup

* chore: minor changes

frontend/src/container/DashboardContainer/visualization/charts/BarChart/BarChart.tsx

@@ -37,6 +37,7 @@ export default function BarChart(props: BarChartProps): JSX.Element {
 				yAxisUnit: rest.yAxisUnit,
 				decimalPrecision: rest.decimalPrecision,
 				isStackedBarChart: isStackedBarChart,
+				canPinTooltip: rest.canPinTooltip,
 			};
 			return <BarChartTooltip {...tooltipProps} />;
 		},
@@ -46,6 +47,7 @@ export default function BarChart(props: BarChartProps): JSX.Element {
 			rest.yAxisUnit,
 			rest.decimalPrecision,
 			isStackedBarChart,
+			rest.canPinTooltip,
 		],
 	);
 

frontend/src/container/DashboardContainer/visualization/charts/ChartWrapper/ChartWrapper.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useRef } from 'react';
+import { useCallback, useMemo, useRef } from 'react';
 import ChartLayout from 'container/DashboardContainer/visualization/layout/ChartLayout/ChartLayout';
 import Legend from 'lib/uPlotV2/components/Legend/Legend';
 import {
@@ -25,11 +25,14 @@ export default function ChartWrapper({
 	showTooltip = true,
 	showLegend = true,
 	canPinTooltip = false,
+	pinKey,
+	onClick,
 	syncMode,
 	syncKey,
 	onDestroy = noop,
 	children,
 	layoutChildren,
+	yAxisUnit,
 	customTooltip,
 	pinnedTooltipElement,
 	'data-testid': testId,
@@ -62,6 +65,13 @@ export default function ChartWrapper({
 		[customTooltip],
 	);
 
+	const syncMetadata = useMemo(
+		() => ({
+			yAxisUnit,
+		}),
+		[yAxisUnit],
+	);
+
 	return (
 		<PlotContextProvider>
 			<ChartLayout
@@ -93,12 +103,15 @@ export default function ChartWrapper({
 							<TooltipPlugin
 								config={config}
 								canPinTooltip={canPinTooltip}
+								pinKey={pinKey}
+								onClick={onClick}
 								syncMode={syncMode}
 								maxWidth={Math.max(
 									TOOLTIP_MIN_WIDTH,
 									averageLegendWidth + TOOLTIP_WIDTH_PADDING,
 								)}
 								syncKey={syncKey}
+								syncMetadata={syncMetadata}
 								render={renderTooltipCallback}
 								pinnedTooltipElement={pinnedTooltipElement}
 							/>

frontend/src/container/DashboardContainer/visualization/charts/Histogram/Histogram.tsx

@@ -24,13 +24,13 @@ export default function Histogram(props: HistogramChartProps): JSX.Element {
 			}
 			const tooltipProps: HistogramTooltipProps = {
 				...props,
-				timezone: rest.timezone,
 				yAxisUnit: rest.yAxisUnit,
 				decimalPrecision: rest.decimalPrecision,
+				canPinTooltip: rest.canPinTooltip,
 			};
 			return <HistogramTooltip {...tooltipProps} />;
 		},
-		[customTooltip, rest.timezone, rest.yAxisUnit, rest.decimalPrecision],
+		[customTooltip, rest.yAxisUnit, rest.decimalPrecision, rest.canPinTooltip],
 	);
 
 	return (

frontend/src/container/DashboardContainer/visualization/charts/TimeSeries/TimeSeries.tsx

@@ -21,10 +21,17 @@ export default function TimeSeries(props: TimeSeriesChartProps): JSX.Element {
 				timezone: rest.timezone,
 				yAxisUnit: rest.yAxisUnit,
 				decimalPrecision: rest.decimalPrecision,
+				canPinTooltip: rest.canPinTooltip,
 			};
 			return <TimeSeriesTooltip {...tooltipProps} />;
 		},
-		[customTooltip, rest.timezone, rest.yAxisUnit, rest.decimalPrecision],
+		[
+			customTooltip,
+			rest.timezone,
+			rest.yAxisUnit,
+			rest.decimalPrecision,
+			rest.canPinTooltip,
+		],
 	);
 
 	return (

frontend/src/container/DashboardContainer/visualization/charts/types.ts

@@ -12,8 +12,11 @@ interface BaseChartProps {
 	height: number;
 	showTooltip?: boolean;
 	showLegend?: boolean;
-	timezone?: Timezone;
 	canPinTooltip?: boolean;
+	/** Key that pins the tooltip while hovering. Defaults to DEFAULT_PIN_TOOLTIP_KEY ('l'). */
+	pinKey?: string;
+	/** Called when the user clicks the uPlot overlay. Receives resolved click data. */
+	onClick?: (clickData: TooltipClickData) => void;
 	yAxisUnit?: string;
 	decimalPrecision?: PrecisionOption;
 	pinnedTooltipElement?: (clickData: TooltipClickData) => React.ReactNode;
@@ -32,18 +35,31 @@ interface UPlotBasedChartProps {
 	layoutChildren?: React.ReactNode;
 }
 
+interface UPlotChartDataProps {
+	yAxisUnit?: string;
+	decimalPrecision?: PrecisionOption;
+}
+
 export interface TimeSeriesChartProps
 	extends BaseChartProps,
-		UPlotBasedChartProps {}
+		UPlotBasedChartProps,
+		UPlotChartDataProps {
+	timezone?: Timezone;
+}
 
 export interface HistogramChartProps
 	extends BaseChartProps,
-		UPlotBasedChartProps {
+		UPlotBasedChartProps,
+		UPlotChartDataProps {
 	isQueriesMerged?: boolean;
 }
 
-export interface BarChartProps extends BaseChartProps, UPlotBasedChartProps {
+export interface BarChartProps
+	extends BaseChartProps,
+		UPlotBasedChartProps,
+		UPlotChartDataProps {
 	isStackedBarChart?: boolean;
+	timezone?: Timezone;
 }
 
 export type ChartProps =

frontend/src/container/DashboardContainer/visualization/panels/BarPanel/BarPanel.tsx

@@ -121,15 +121,16 @@ function BarPanel(props: PanelWrapperProps): JSX.Element {
 					legendConfig={{
 						position: widget?.legendPosition ?? LegendPosition.BOTTOM,
 					}}
+					canPinTooltip
 					plotRef={onPlotRef}
 					onDestroy={onPlotDestroy}
-					yAxisUnit={widget.yAxisUnit}
-					decimalPrecision={widget.decimalPrecision}
 					data={chartData as uPlot.AlignedData}
 					width={containerDimensions.width}
 					height={containerDimensions.height}
 					layoutChildren={layoutChildren}
 					isStackedBarChart={widget.stackedBarChart ?? false}
+					yAxisUnit={widget.yAxisUnit}
+					decimalPrecision={widget.decimalPrecision}
 					timezone={timezone}
 				>
 					<ContextMenu

frontend/src/container/DashboardContainer/visualization/panels/HistogramPanel/HistogramPanel.tsx

@@ -3,8 +3,6 @@ import { PanelWrapperProps } from 'container/PanelWrapper/panelWrapper.types';
 import { useIsDarkMode } from 'hooks/useDarkMode';
 import { useResizeObserver } from 'hooks/useDimensions';
 import { LegendPosition } from 'lib/uPlotV2/components/types';
-import { DashboardCursorSync } from 'lib/uPlotV2/plugins/TooltipPlugin/types';
-import { useTimezone } from 'providers/Timezone';
 import uPlot from 'uplot';
 
 import Histogram from '../../charts/Histogram/Histogram';
@@ -29,7 +27,6 @@ function HistogramPanel(props: PanelWrapperProps): JSX.Element {
 	const containerDimensions = useResizeObserver(graphRef);
 
 	const isDarkMode = useIsDarkMode();
-	const { timezone } = useTimezone();
 
 	const config = useMemo(() => {
 		return prepareHistogramPanelConfig({
@@ -92,11 +89,10 @@ function HistogramPanel(props: PanelWrapperProps): JSX.Element {
 					onDestroy={(): void => {
 						uPlotRef.current = null;
 					}}
-					isQueriesMerged={widget.mergeAllActiveQueries}
+					canPinTooltip
 					yAxisUnit={widget.yAxisUnit}
 					decimalPrecision={widget.decimalPrecision}
-					syncMode={DashboardCursorSync.Crosshair}
-					timezone={timezone}
+					isQueriesMerged={widget.mergeAllActiveQueries}
 					data={chartData as uPlot.AlignedData}
 					width={containerDimensions.width}
 					height={containerDimensions.height}

frontend/src/container/DashboardContainer/visualization/panels/HistogramPanel/__tests__/HistogramPanel.test.tsx

@@ -48,8 +48,8 @@ jest.mock(
 					{JSON.stringify({
 						legendPosition: props.legendConfig?.position,
 						isQueriesMerged: props.isQueriesMerged,
-						yAxisUnit: props.yAxisUnit,
-						decimalPrecision: props.decimalPrecision,
+						yAxisUnit: props?.yAxisUnit,
+						decimalPrecision: props?.decimalPrecision,
 					})}
 				</div>
 				{props.layoutChildren}

frontend/src/container/DashboardContainer/visualization/panels/TimeSeriesPanel/TimeSeriesPanel.tsx

@@ -112,9 +112,10 @@ function TimeSeriesPanel(props: PanelWrapperProps): JSX.Element {
 					legendConfig={{
 						position: widget?.legendPosition ?? LegendPosition.BOTTOM,
 					}}
+					canPinTooltip
+					timezone={timezone}
 					yAxisUnit={widget.yAxisUnit}
 					decimalPrecision={widget.decimalPrecision}
-					timezone={timezone}
 					data={chartData as uPlot.AlignedData}
 					width={containerDimensions.width}
 					height={containerDimensions.height}

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

@@ -1,4 +1,4 @@
-.uplot-tooltip-container {
+.container {
 	font-family: 'Inter';
 	font-size: 12px;
 	background: var(--bg-ink-300);
@@ -10,63 +10,23 @@
 	flex-direction: column;
 	gap: 8px;
 
+	&.pinned {
+		border-color: var(--bg-robin-500);
+	}
+
 	&.lightMode {
 		background: var(--bg-vanilla-100);
 		color: var(--bg-ink-500);
 		border: 1px solid var(--bg-vanilla-300);
 
-		.uplot-tooltip-list {
-			&::-webkit-scrollbar-thumb {
-				background: var(--bg-vanilla-400);
-			}
-		}
-
-		.uplot-tooltip-divider {
+		.divider {
 			background-color: var(--bg-vanilla-300);
 		}
 	}
 
-	.uplot-tooltip-header-container {
-		padding: 1rem 1rem 0 1rem;
-		display: flex;
-		flex-direction: column;
-		gap: 8px;
-
-		&:last-child {
-			padding-bottom: 1rem;
-		}
-
-		.uplot-tooltip-header {
-			font-size: 13px;
-			font-weight: 500;
-		}
-	}
-
-	.uplot-tooltip-divider {
+	.divider {
 		width: 100%;
 		height: 1px;
 		background-color: var(--bg-ink-100);
 	}
-
-	.uplot-tooltip-list {
-		// Virtuoso absolutely positions its item rows; left: 0 prevents accidental
-		// horizontal offset when the scroller has padding or transform applied.
-		div[data-viewport-type='element'] {
-			left: 0;
-			padding: 4px 8px 4px 16px;
-		}
-
-		&::-webkit-scrollbar {
-			width: 0.3rem;
-		}
-
-		&::-webkit-scrollbar-track {
-			background: transparent;
-		}
-
-		&::-webkit-scrollbar-thumb {
-			background: var(--bg-slate-100);
-			border-radius: 0.5rem;
-		}
-	}
 }

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

@@ -1,71 +1,31 @@
-import { useMemo, useState } from 'react';
-import { Virtuoso } from 'react-virtuoso';
+import { useMemo } from 'react';
 import cx from 'classnames';
-import { DATE_TIME_FORMATS } from 'constants/dateTimeFormats';
-import dayjs from 'dayjs';
 import { useIsDarkMode } from 'hooks/useDarkMode';
-import { useTimezone } from 'providers/Timezone';
 
 import { TooltipProps } from '../types';
-import TooltipItem from './components/TooltipItem/TooltipItem';
+import TooltipFooter from './components/TooltipFooter/TooltipFooter';
+import TooltipHeader from './components/TooltipHeader/TooltipHeader';
+import TooltipList from './components/TooltipList/TooltipList';
 
 import Styles from './Tooltip.module.scss';
 
-// Fallback per-item height used for the initial size estimate before
-// Virtuoso reports the real total height via totalListHeightChanged.
-const TOOLTIP_ITEM_HEIGHT = 38;
-const LIST_MAX_HEIGHT = 300;
-
 export default function Tooltip({
 	uPlotInstance,
 	timezone,
 	content,
 	showTooltipHeader = true,
+	isPinned,
+	canPinTooltip,
+	dismiss,
 }: TooltipProps): JSX.Element {
 	const isDarkMode = useIsDarkMode();
-	const { timezone: userTimezone } = useTimezone();
-	const [totalListHeight, setTotalListHeight] = useState(0);
 
 	const tooltipContent = useMemo(() => content ?? [], [content]);
-
-	const resolvedTimezone = timezone?.value ?? userTimezone.value;
-
-	const headerTitle = useMemo(() => {
-		if (!showTooltipHeader) {
-			return null;
-		}
-		const cursorIdx = uPlotInstance.cursor.idx;
-		if (cursorIdx == null) {
-			return null;
-		}
-		const timestamp = uPlotInstance.data[0]?.[cursorIdx];
-		if (timestamp == null) {
-			return null;
-		}
-		return dayjs(timestamp * 1000)
-			.tz(resolvedTimezone)
-			.format(DATE_TIME_FORMATS.MONTH_DATETIME_SECONDS);
-	}, [
-		resolvedTimezone,
-		uPlotInstance.data,
-		uPlotInstance.cursor.idx,
-		showTooltipHeader,
-	]);
-
 	const activeItem = useMemo(
 		() => tooltipContent.find((item) => item.isActive) ?? null,
 		[tooltipContent],
 	);
 
-	// Use the measured height from Virtuoso when available; fall back to a
-	// per-item estimate on the first render.  Math.ceil prevents a 1 px
-	// subpixel rounding gap from triggering a spurious scrollbar.
-	const virtuosoHeight = useMemo(() => {
-		return totalListHeight > 0
-			? Math.ceil(Math.min(totalListHeight, LIST_MAX_HEIGHT))
-			: Math.min(tooltipContent.length * TOOLTIP_ITEM_HEIGHT, LIST_MAX_HEIGHT);
-	}, [totalListHeight, tooltipContent.length]);
-
 	const showHeader = showTooltipHeader || activeItem != null;
 	// With a single series the active item is fully represented in the header —
 	// hide the divider and list to avoid showing a duplicate row.
@@ -74,46 +34,28 @@ export default function Tooltip({
 
 	return (
 		<div
-			className={cx(Styles.uplotTooltipContainer, !isDarkMode && Styles.lightMode)}
+			className={cx(
+				Styles.container,
+				!isDarkMode && Styles.lightMode,
+				isPinned && Styles.pinned,
+			)}
 			data-testid="uplot-tooltip-container"
 		>
 			{showHeader && (
-				<div className={Styles.uplotTooltipHeaderContainer}>
-					{showTooltipHeader && headerTitle && (
-						<div
-							className={Styles.uplotTooltipHeader}
-							data-testid="uplot-tooltip-header"
-						>
-							<span>{headerTitle}</span>
-						</div>
-					)}
-
-					{activeItem && (
-						<TooltipItem
-							item={activeItem}
-							isItemActive={true}
-							containerTestId="uplot-tooltip-pinned"
-							markerTestId="uplot-tooltip-pinned-marker"
-							contentTestId="uplot-tooltip-pinned-content"
-						/>
-					)}
-				</div>
-			)}
-
-			{showDivider && <span className={Styles.uplotTooltipDivider} />}
-
-			{showList && (
-				<Virtuoso
-					className={Styles.uplotTooltipList}
-					data-testid="uplot-tooltip-list"
-					data={tooltipContent}
-					style={{ height: virtuosoHeight, width: '100%' }}
-					totalListHeightChanged={setTotalListHeight}
-					itemContent={(_, item): JSX.Element => (
-						<TooltipItem item={item} isItemActive={false} />
-					)}
+				<TooltipHeader
+					uPlotInstance={uPlotInstance}
+					timezone={timezone}
+					showTooltipHeader={showTooltipHeader}
+					isPinned={isPinned}
+					activeItem={activeItem}
 				/>
 			)}
+
+			{showDivider && <span className={Styles.divider} />}
+
+			{showList && <TooltipList content={tooltipContent} />}
+
+			{canPinTooltip && <TooltipFooter isPinned={isPinned} dismiss={dismiss} />}
 		</div>
 	);
 }

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

@@ -1,5 +1,6 @@
 import React from 'react';
 import { VirtuosoMockContext } from 'react-virtuoso';
+import userEvent from '@testing-library/user-event';
 import { DATE_TIME_FORMATS } from 'constants/dateTimeFormats';
 import dayjs from 'dayjs';
 import { useIsDarkMode } from 'hooks/useDarkMode';
@@ -191,3 +192,85 @@ describe('Tooltip', () => {
 		expect(list).toHaveStyle({ height: '76px' });
 	});
 });
+
+describe('Tooltip footer hint', () => {
+	beforeEach(() => {
+		jest.clearAllMocks();
+		mockUseIsDarkMode.mockReturnValue(false);
+	});
+
+	it('renders footer with "Press L to lock" hint when not pinned', () => {
+		renderTooltip({ isPinned: false });
+
+		const footer = screen.getByTestId('uplot-tooltip-footer');
+		expect(footer).toBeInTheDocument();
+		expect(footer).toHaveTextContent('Press');
+		expect(footer).toHaveTextContent('L');
+		expect(footer).toHaveTextContent('to lock');
+	});
+
+	it('renders footer with "Press L or Esc to unlock" hint when pinned', () => {
+		renderTooltip({ isPinned: true });
+
+		const footer = screen.getByTestId('uplot-tooltip-footer');
+		expect(footer).toHaveTextContent('Press');
+		expect(footer).toHaveTextContent('L');
+		expect(footer).toHaveTextContent('Esc');
+		expect(footer).toHaveTextContent('to unlock');
+	});
+
+	it('does not render Unpin button when not pinned', () => {
+		renderTooltip({ isPinned: false });
+
+		expect(screen.queryByTestId('uplot-tooltip-unpin')).not.toBeInTheDocument();
+	});
+
+	it('renders Unpin button when pinned', () => {
+		renderTooltip({ isPinned: true });
+
+		const unpinBtn = screen.getByTestId('uplot-tooltip-unpin');
+		expect(unpinBtn).toBeInTheDocument();
+		expect(unpinBtn).toHaveAttribute('aria-label', 'Unpin tooltip');
+	});
+
+	it('calls dismiss when Unpin button is clicked', async () => {
+		const dismiss = jest.fn();
+		renderTooltip({ isPinned: true, dismiss });
+
+		const user = userEvent.setup();
+		const unpinBtn = screen.getByTestId('uplot-tooltip-unpin');
+		await user.click(unpinBtn);
+
+		expect(dismiss).toHaveBeenCalledTimes(1);
+	});
+
+	it('footer has role="status" for screen reader announcements', () => {
+		renderTooltip();
+
+		const footer = screen.getByRole('status');
+		expect(footer).toBeInTheDocument();
+	});
+});
+
+describe('Tooltip header status pill', () => {
+	beforeEach(() => {
+		jest.clearAllMocks();
+		mockUseIsDarkMode.mockReturnValue(false);
+	});
+
+	it('shows Pinned status when pinned and header is visible', () => {
+		const uPlotInstance = createUPlotInstance(0);
+
+		renderTooltip({ uPlotInstance, isPinned: true });
+
+		expect(screen.getByText('Pinned')).toBeInTheDocument();
+	});
+
+	it('does not render status pill when showTooltipHeader is false', () => {
+		const uPlotInstance = createUPlotInstance(0);
+
+		renderTooltip({ uPlotInstance, showTooltipHeader: false, isPinned: false });
+
+		expect(screen.queryByTestId('uplot-tooltip-status')).not.toBeInTheDocument();
+	});
+});

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

@@ -0,0 +1,29 @@
+.kbd {
+	display: inline-flex;
+	align-items: center;
+	justify-content: center;
+	min-width: 18px;
+	height: 18px;
+	padding: 0 5px;
+	border-radius: 3px;
+	background: var(--bg-ink-200);
+	border: 1px solid var(--bg-slate-200);
+	border-bottom-width: 2px;
+	color: var(--bg-vanilla-100);
+	font-family: 'Space Mono', monospace;
+	font-size: 10px;
+	font-weight: 600;
+	line-height: 1;
+
+	&.lightMode {
+		background: var(--bg-vanilla-200);
+		border-color: var(--bg-vanilla-400);
+		color: var(--bg-ink-400);
+	}
+
+	&.pinned {
+		background: rgba(78, 116, 248, 0.12);
+		border-color: rgba(78, 116, 248, 0.5);
+		color: var(--bg-robin-300);
+	}
+}

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

@@ -0,0 +1,27 @@
+import cx from 'classnames';
+import { useIsDarkMode } from 'hooks/useDarkMode';
+
+import Styles from './Kbd.module.scss';
+
+interface KbdProps {
+	children: React.ReactNode;
+	isPinned?: boolean;
+}
+
+export default function Kbd({
+	children,
+	isPinned = false,
+}: KbdProps): JSX.Element {
+	const isDarkMode = useIsDarkMode();
+
+	return (
+		<kbd
+			className={cx(Styles.kbd, {
+				[Styles.lightMode]: !isDarkMode,
+				[Styles.pinned]: isPinned,
+			})}
+		>
+			{children}
+		</kbd>
+	);
+}

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

@@ -0,0 +1,67 @@
+.footer {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: 10px;
+	padding: 7px 12px;
+	border-top: 1px solid var(--bg-slate-400);
+	background: rgba(0, 0, 0, 0.25);
+	border-radius: 0 0 6px 6px;
+	// Pull the footer up against the flex gap from the parent container.
+	margin-top: -8px;
+
+	&.lightMode {
+		background: rgba(0, 0, 0, 0.04);
+		border-top-color: var(--bg-vanilla-300);
+
+		.hint {
+			color: var(--bg-ink-400);
+		}
+
+		.unpin-button {
+			color: var(--bg-ink-400);
+			border-color: var(--bg-vanilla-300);
+
+			&:hover {
+				color: var(--bg-ink-500);
+				border-color: var(--bg-vanilla-400);
+				background: var(--bg-vanilla-200);
+			}
+		}
+	}
+
+	&.footer-pinned {
+		background: rgba(78, 116, 248, 0.06);
+		border-top-color: rgba(78, 116, 248, 0.25);
+	}
+
+	.hint {
+		display: flex;
+		align-items: center;
+		gap: 5px;
+		font-size: 11px;
+		color: var(--bg-vanilla-400);
+	}
+
+	.unpin-button {
+		display: inline-flex;
+		align-items: center;
+		gap: 5px;
+		padding: 3px 8px 3px 6px;
+		background: transparent;
+		border: 1px solid var(--bg-slate-200);
+		border-radius: 3px;
+		color: var(--bg-vanilla-400);
+		font-family: 'Inter', sans-serif;
+		font-size: 11px;
+		cursor: pointer;
+		transition: all 150ms ease;
+		flex-shrink: 0;
+
+		&:hover {
+			color: var(--bg-vanilla-100);
+			border-color: var(--bg-slate-100);
+			background: var(--bg-ink-200);
+		}
+	}
+}

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

@@ -0,0 +1,65 @@
+import cx from 'classnames';
+import { useIsDarkMode } from 'hooks/useDarkMode';
+import { DEFAULT_PIN_TOOLTIP_KEY } from 'lib/uPlotV2/plugins/TooltipPlugin/types';
+import { X } from 'lucide-react';
+
+import Kbd from '../Kbd/Kbd';
+
+import Styles from './TooltipFooter.module.scss';
+
+interface TooltipFooterProps {
+	pinKey?: string;
+	isPinned: boolean;
+	dismiss: () => void;
+}
+
+export default function TooltipFooter({
+	pinKey = DEFAULT_PIN_TOOLTIP_KEY,
+	isPinned,
+	dismiss,
+}: TooltipFooterProps): JSX.Element {
+	const isDarkMode = useIsDarkMode();
+
+	return (
+		<div
+			className={cx(
+				Styles.footer,
+				!isDarkMode && Styles.lightMode,
+				isPinned && Styles.footerPinned,
+			)}
+			role="status"
+			data-testid="uplot-tooltip-footer"
+		>
+			<div className={Styles.hint}>
+				{isPinned ? (
+					<>
+						<span>Press</span>
+						<Kbd isPinned>{pinKey.toUpperCase()}</Kbd>
+						<span>or</span>
+						<Kbd isPinned>Esc</Kbd>
+						<span>to unpin</span>
+					</>
+				) : (
+					<>
+						<span>Press</span>
+						<Kbd>{pinKey.toUpperCase()}</Kbd>
+						<span>to pin the tooltip</span>
+					</>
+				)}
+			</div>
+
+			{isPinned && (
+				<button
+					type="button"
+					className={Styles.unpinButton}
+					onClick={dismiss}
+					aria-label="Unpin tooltip"
+					data-testid="uplot-tooltip-unpin"
+				>
+					<X size={10} />
+					<span>Unpin</span>
+				</button>
+			)}
+		</div>
+	);
+}

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

@@ -0,0 +1,39 @@
+.header-container {
+	padding: 1rem 1rem 0 1rem;
+	display: flex;
+	flex-direction: column;
+	gap: 8px;
+
+	&:last-child {
+		padding-bottom: 1rem;
+	}
+
+	.header-row {
+		font-size: 13px;
+		font-weight: 500;
+		display: flex;
+		align-items: center;
+		justify-content: space-between;
+		gap: 8px;
+	}
+
+	.status {
+		display: flex;
+		align-items: center;
+		gap: 5px;
+		font-size: 10px;
+		font-weight: 600;
+		text-transform: uppercase;
+		letter-spacing: 0.05em;
+		color: var(--bg-slate-50);
+		flex-shrink: 0;
+
+		&.statusLightMode {
+			color: var(--bg-ink-300);
+		}
+
+		&.status-pinned {
+			color: var(--bg-robin-400);
+		}
+	}
+}

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

@@ -0,0 +1,94 @@
+import { useMemo } from 'react';
+import cx from 'classnames';
+import type { Timezone } from 'components/CustomTimePicker/timezoneUtils';
+import { DATE_TIME_FORMATS } from 'constants/dateTimeFormats';
+import dayjs from 'dayjs';
+import { useIsDarkMode } from 'hooks/useDarkMode';
+import { Pin } from 'lucide-react';
+import { useTimezone } from 'providers/Timezone';
+import type uPlot from 'uplot';
+
+import { TooltipContentItem } from '../../../types';
+import TooltipItem from '../TooltipItem/TooltipItem';
+
+import Styles from './TooltipHeader.module.scss';
+
+interface TooltipHeaderProps {
+	uPlotInstance: uPlot;
+	timezone?: Timezone;
+	showTooltipHeader: boolean;
+	isPinned: boolean;
+	activeItem: TooltipContentItem | null;
+}
+
+export default function TooltipHeader({
+	uPlotInstance,
+	timezone,
+	showTooltipHeader,
+	isPinned,
+	activeItem,
+}: TooltipHeaderProps): JSX.Element {
+	const isDarkMode = useIsDarkMode();
+	const { timezone: userTimezone } = useTimezone();
+	const resolvedTimezone = timezone?.value ?? userTimezone.value;
+
+	const headerTitle = useMemo(() => {
+		if (!showTooltipHeader) {
+			return null;
+		}
+		const cursorIdx = uPlotInstance.cursor.idx;
+		if (cursorIdx == null) {
+			return null;
+		}
+		const timestamp = uPlotInstance.data[0]?.[cursorIdx];
+		if (timestamp == null) {
+			return null;
+		}
+		return dayjs(timestamp * 1000)
+			.tz(resolvedTimezone)
+			.format(DATE_TIME_FORMATS.MONTH_DATETIME_SECONDS);
+	}, [
+		resolvedTimezone,
+		uPlotInstance.data,
+		uPlotInstance.cursor.idx,
+		showTooltipHeader,
+	]);
+
+	return (
+		<div
+			className={Styles.headerContainer}
+			data-testid="uplot-tooltip-header-container"
+		>
+			{showTooltipHeader && headerTitle && (
+				<div className={Styles.headerRow}>
+					<span>{headerTitle}</span>
+					<div
+						className={cx(
+							Styles.status,
+							!isDarkMode && Styles.statusLightMode,
+							isPinned && Styles.statusPinned,
+						)}
+						data-testid="uplot-tooltip-status"
+					>
+						{isPinned && (
+							<>
+								<Pin size={12} />
+								<span>Pinned</span>
+							</>
+						)}
+					</div>
+				</div>
+			)}
+
+			{activeItem && (
+				<TooltipItem
+					item={activeItem}
+					isItemActive={true}
+					containerTestId="uplot-tooltip-pinned"
+					markerTestId="uplot-tooltip-pinned-marker"
+					contentTestId="uplot-tooltip-pinned-content"
+				/>
+			)}
+		</div>
+	);
+}

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

@@ -0,0 +1,27 @@
+.list {
+	// Virtuoso absolutely positions its item rows; left: 0 prevents accidental
+	// horizontal offset when the scroller has padding or transform applied.
+	div[data-viewport-type='element'] {
+		left: 0;
+		padding: 4px 8px 4px 16px;
+	}
+
+	&::-webkit-scrollbar {
+		width: 0.3rem;
+	}
+
+	&::-webkit-scrollbar-track {
+		background: transparent;
+	}
+
+	&::-webkit-scrollbar-thumb {
+		background: var(--bg-slate-100);
+		border-radius: 0.5rem;
+	}
+
+	&.lightMode {
+		&::-webkit-scrollbar-thumb {
+			background: var(--bg-vanilla-400);
+		}
+	}
+}

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

@@ -0,0 +1,48 @@
+import { useMemo, useState } from 'react';
+import { Virtuoso } from 'react-virtuoso';
+import cx from 'classnames';
+import { useIsDarkMode } from 'hooks/useDarkMode';
+
+import { TooltipContentItem } from '../../../types';
+import TooltipItem from '../TooltipItem/TooltipItem';
+
+import Styles from './TooltipList.module.scss';
+
+// Fallback per-item height before Virtuoso reports the real total.
+const TOOLTIP_ITEM_HEIGHT = 38;
+const LIST_MAX_HEIGHT = 300;
+
+interface TooltipListProps {
+	content: TooltipContentItem[];
+}
+
+export default function TooltipList({
+	content,
+}: TooltipListProps): JSX.Element {
+	const isDarkMode = useIsDarkMode();
+	const [totalListHeight, setTotalListHeight] = useState(0);
+
+	// Use the measured height from Virtuoso when available; fall back to a
+	// per-item estimate on first render. Math.ceil prevents a 1 px
+	// subpixel rounding gap from triggering a spurious scrollbar.
+	const height = useMemo(
+		() =>
+			totalListHeight > 0
+				? Math.ceil(Math.min(totalListHeight, LIST_MAX_HEIGHT))
+				: Math.min(content.length * TOOLTIP_ITEM_HEIGHT, LIST_MAX_HEIGHT),
+		[totalListHeight, content.length],
+	);
+
+	return (
+		<Virtuoso
+			className={cx(Styles.list, !isDarkMode && Styles.lightMode)}
+			data-testid="uplot-tooltip-list"
+			data={content}
+			style={{ height, width: '100%' }}
+			totalListHeightChanged={setTotalListHeight}
+			itemContent={(_, item): JSX.Element => (
+				<TooltipItem item={item} isItemActive={false} />
+			)}
+		/>
+	);
+}

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

@@ -62,10 +62,11 @@ export interface TooltipRenderArgs {
 
 export interface BaseTooltipProps {
 	showTooltipHeader?: boolean;
-	timezone?: Timezone;
+	canPinTooltip?: boolean;
 	yAxisUnit?: string;
 	decimalPrecision?: PrecisionOption;
 	content?: TooltipContentItem[];
+	timezone?: Timezone;
 }
 
 export interface TimeSeriesTooltipProps

frontend/src/lib/uPlotV2/plugins/TooltipPlugin/TooltipPlugin.styles.scss

@@ -11,10 +11,6 @@
 	opacity: 0;
 	pointer-events: none;
 
-	&.pinned {
-		box-shadow: 0 6px 16px rgba(0, 0, 0, 0.2);
-	}
-
 	&.visible {
 		opacity: 1;
 		pointer-events: all;

frontend/src/lib/uPlotV2/plugins/TooltipPlugin/TooltipPlugin.tsx

@@ -1,9 +1,9 @@
 import { useCallback, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { createPortal } from 'react-dom';
 import cx from 'classnames';
-import { getFocusedSeriesAtPosition } from 'lib/uPlotLib/plugins/onClickPlugin';
 import uPlot from 'uplot';
 
+import { syncCursorRegistry } from './syncCursorRegistry';
 import {
 	createInitialControllerState,
 	createSetCursorHandler,
@@ -16,14 +16,18 @@ import {
 } from './tooltipController';
 import {
 	DashboardCursorSync,
-	TooltipClickData,
+	DEFAULT_PIN_TOOLTIP_KEY,
 	TooltipControllerContext,
 	TooltipControllerState,
 	TooltipLayoutInfo,
 	TooltipPluginProps,
 	TooltipViewState,
 } from './types';
-import { createInitialViewState, createLayoutObserver } from './utils';
+import {
+	buildClickData,
+	createInitialViewState,
+	createLayoutObserver,
+} from './utils';
 
 import './TooltipPlugin.styles.scss';
 
@@ -40,8 +44,11 @@ export default function TooltipPlugin({
 	maxHeight = 600,
 	syncMode = DashboardCursorSync.None,
 	syncKey = '_tooltip_sync_global_',
+	syncMetadata,
 	pinnedTooltipElement,
 	canPinTooltip = false,
+	pinKey = DEFAULT_PIN_TOOLTIP_KEY,
+	onClick,
 }: TooltipPluginProps): JSX.Element | null {
 	const containerRef = useRef<HTMLDivElement>(null);
 	const rafId = useRef<number | null>(null);
@@ -100,7 +107,29 @@ export default function TooltipPlugin({
 		// crosshair / tooltip can follow the dashboard-wide cursor.
 		if (syncMode !== DashboardCursorSync.None && config.scales[0]?.props.time) {
 			config.setCursor({
-				sync: { key: syncKey, scales: ['x', null] },
+				sync: { key: syncKey, scales: ['x', 'y'] },
+			});
+
+			// Show the horizontal crosshair only when the receiving panel shares
+			// the same y-axis unit as the source panel. When this panel is the
+			// source (cursor.event != null) the line is always shown and this
+			// panel's metadata is written to the registry so receivers can read it.
+			config.addHook('setCursor', (u: uPlot): void => {
+				const yCursorEl = u.root.querySelector<HTMLElement>('.u-cursor-y');
+				if (!yCursorEl) {
+					return;
+				}
+
+				if (u.cursor.event != null) {
+					// This panel is the source — publish metadata and always show line.
+					syncCursorRegistry.setMetadata(syncKey, syncMetadata);
+					yCursorEl.style.display = '';
+				} else {
+					// This panel is receiving sync — show only if units match.
+					const sourceMeta = syncCursorRegistry.getMetadata(syncKey);
+					yCursorEl.style.display =
+						sourceMeta?.yAxisUnit === syncMetadata?.yAxisUnit ? '' : 'none';
+				}
 			});
 		}
 
@@ -135,13 +164,14 @@ export default function TooltipPlugin({
 
 		// Attach / detach global listeners when pin state changes so
 		// we can detect when the user interacts outside the tooltip.
+		// Keyboard unpinning is handled exclusively in handleKeyDown so
+		// that only L (toggle) and Escape (release) can dismiss — not
+		// arbitrary keystrokes like arrow keys or Tab.
 		function toggleOutsideListeners(enable: boolean): void {
 			if (enable) {
 				document.addEventListener('mousedown', onOutsideInteraction, true);
-				document.addEventListener('keydown', onOutsideInteraction, true);
 			} else {
 				document.removeEventListener('mousedown', onOutsideInteraction, true);
-				document.removeEventListener('keydown', onOutsideInteraction, true);
 			}
 		}
 
@@ -259,66 +289,84 @@ export default function TooltipPlugin({
 			}
 		};
 
-		// When pinning is enabled, a click on the plot overlay while
-		// hovering converts the transient tooltip into a pinned one.
-		// Uses getPlot(controller) to avoid closing over u (plot), which
-		// would retain the plot and detached canvases across unmounts.
-		const handleUPlotOverClick = (event: MouseEvent): void => {
+		// Handles all tooltip-pin keyboard interactions:
+		//   Escape  — always releases the tooltip when pinned (never steals Escape
+		//             from other handlers since we do not call stopPropagation).
+		//   pinKey  — toggles: pins when hovering+unpinned, unpins when pinned.
+		const handleKeyDown = (event: KeyboardEvent): void => {
+			// Escape: release-only (never toggles on).
+			if (event.key === 'Escape') {
+				if (controller.pinned) {
+					dismissTooltip();
+				}
+				return;
+			}
+
+			if (event.key.toLowerCase() !== pinKey.toLowerCase()) {
+				return;
+			}
+
+			// Toggle off: L pressed while already pinned.
+			if (controller.pinned) {
+				dismissTooltip();
+				return;
+			}
+
+			// Toggle on: L pressed while hovering.
 			const plot = getPlot(controller);
+			if (
+				!plot ||
+				!controller.hoverActive ||
+				controller.focusedSeriesIndex == null
+			) {
+				return;
+			}
+
+			const cursorLeft = plot.cursor.left ?? -1;
+			const cursorTop = plot.cursor.top ?? -1;
+			if (cursorLeft < 0 || cursorTop < 0) {
+				return;
+			}
+
+			const plotRect = plot.over.getBoundingClientRect();
+			const syntheticEvent = ({
+				clientX: plotRect.left + cursorLeft,
+				clientY: plotRect.top + cursorTop,
+				target: plot.over,
+				offsetX: cursorLeft,
+				offsetY: cursorTop,
+			} as unknown) as MouseEvent;
+
+			controller.clickData = buildClickData(syntheticEvent, plot);
+			controller.pinned = true;
+			scheduleRender(true);
+		};
+
+		// Forward overlay clicks to the consumer-provided onClick callback.
+		const handleOverClick = (event: MouseEvent): void => {
+			const plot = getPlot(controller);
+			/**
+			 * Only trigger onClick if the click happened on the plot overlay and there is a focused series.
+			 * It also ensures that clicks only trigger onClick when there is a relevant data point (i.e. a focused series) to provide context for the click.
+			 */
 			if (
 				plot &&
 				event.target === plot.over &&
-				controller.hoverActive &&
-				!controller.pinned &&
 				controller.focusedSeriesIndex != null
 			) {
-				const xValue = plot.posToVal(event.offsetX, 'x');
-				const yValue = plot.posToVal(event.offsetY, 'y');
-				const focusedSeries = getFocusedSeriesAtPosition(event, plot);
-
-				let clickedDataTimestamp = xValue;
-				if (focusedSeries) {
-					const dataIndex = plot.posToIdx(event.offsetX);
-					const xSeriesData = plot.data[0];
-					if (
-						xSeriesData &&
-						dataIndex >= 0 &&
-						dataIndex < xSeriesData.length &&
-						xSeriesData[dataIndex] !== undefined
-					) {
-						clickedDataTimestamp = xSeriesData[dataIndex];
-					}
-				}
-
-				const clickData: TooltipClickData = {
-					xValue,
-					yValue,
-					focusedSeries,
-					clickedDataTimestamp,
-					mouseX: event.offsetX,
-					mouseY: event.offsetY,
-					absoluteMouseX: event.clientX,
-					absoluteMouseY: event.clientY,
-				};
-
-				controller.clickData = clickData;
-
-				setTimeout(() => {
-					controller.pinned = true;
-					scheduleRender(true);
-				}, 0);
+				const clickData = buildClickData(event, plot);
+				onClick?.(clickData);
 			}
 		};
 
 		let overClickHandler: ((event: MouseEvent) => void) | null = null;
 
-		// Called once per uPlot instance; used to store the instance
-		// on the controller and optionally attach the pinning handler.
+		// Called once per uPlot instance; used to store the instance on the controller.
 		const handleInit = (u: uPlot): void => {
 			controller.plot = u;
 			updateState({ hasPlot: true });
-			if (canPinTooltip) {
-				overClickHandler = handleUPlotOverClick;
+			if (onClick) {
+				overClickHandler = handleOverClick;
 				u.over.addEventListener('click', overClickHandler);
 			}
 		};
@@ -365,13 +413,18 @@ export default function TooltipPlugin({
 
 		window.addEventListener('resize', handleWindowResize);
 		window.addEventListener('scroll', handleScroll, true);
+		if (canPinTooltip) {
+			document.addEventListener('keydown', handleKeyDown, true);
+		}
 
 		return (): void => {
 			layoutRef.current?.observer.disconnect();
 			window.removeEventListener('resize', handleWindowResize);
 			window.removeEventListener('scroll', handleScroll, true);
 			document.removeEventListener('mousedown', onOutsideInteraction, true);
-			document.removeEventListener('keydown', onOutsideInteraction, true);
+			if (canPinTooltip) {
+				document.removeEventListener('keydown', handleKeyDown, true);
+			}
 			cancelPendingRender();
 			removeReadyHook();
 			removeInitHook();
@@ -381,9 +434,7 @@ export default function TooltipPlugin({
 			removeSetCursorHook();
 			if (overClickHandler) {
 				const plot = getPlot(controller);
-				if (plot) {
-					plot.over.removeEventListener('click', overClickHandler);
-				}
+				plot?.over.removeEventListener('click', overClickHandler);
 				overClickHandler = null;
 			}
 			clearPlotReferences();
@@ -423,8 +474,12 @@ export default function TooltipPlugin({
 	}, [isHovering, hasPlot]);
 
 	const tooltipBody = useMemo(() => {
-		if (isPinned && pinnedTooltipElement != null && viewState.clickData != null) {
-			return pinnedTooltipElement(viewState.clickData);
+		if (isPinned) {
+			if (pinnedTooltipElement != null && viewState.clickData != null) {
+				return pinnedTooltipElement(viewState.clickData);
+			}
+			// No custom pinned element — keep showing the last hover contents.
+			return contents ?? null;
 		}
 
 		if (isHovering) {

frontend/src/lib/uPlotV2/plugins/TooltipPlugin/syncCursorRegistry.ts

@@ -0,0 +1,24 @@
+import type { TooltipSyncMetadata } from './types';
+
+/**
+ * Module-level registry that tracks the metadata of the panel currently
+ * acting as the cursor source (the one being hovered) per sync group.
+ *
+ * uPlot fires the source panel's setCursor hook before broadcasting to
+ * receivers, so the registry is always populated before receivers read it.
+ *
+ * Receivers use this to make decisions such as:
+ * - Whether to show the horizontal crosshair line (matching yAxisUnit)
+ * - Future: what to render inside the tooltip (matching groupBy, etc.)
+ */
+const metadataBySyncKey = new Map<string, TooltipSyncMetadata | undefined>();
+
+export const syncCursorRegistry = {
+	setMetadata(syncKey: string, metadata: TooltipSyncMetadata | undefined): void {
+		metadataBySyncKey.set(syncKey, metadata);
+	},
+
+	getMetadata(syncKey: string): TooltipSyncMetadata | undefined {
+		return metadataBySyncKey.get(syncKey);
+	},
+};

frontend/src/lib/uPlotV2/plugins/TooltipPlugin/tooltipController.ts

@@ -102,6 +102,12 @@ export function updateHoverState(
 	controller: TooltipControllerState,
 	syncTooltipWithDashboard: boolean,
 ): void {
+	// When pinned, keep hoverActive stable so the tooltip stays visible
+	// until explicitly dismissed — the cursor lock fires asynchronously
+	// and setSeries/setLegend can otherwise race and clear hoverActive.
+	if (controller.pinned) {
+		return;
+	}
 	// When the cursor is driven by dashboard‑level sync, we only show
 	// the tooltip if the plot is in viewport and at least one series
 	// is active. Otherwise we fall back to local interaction logic.

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

@@ -11,6 +11,9 @@ import type { UPlotConfigBuilder } from '../../config/UPlotConfigBuilder';
 
 export const TOOLTIP_OFFSET = 10;
 
+// Default key that pins the tooltip while hovering over the chart.
+export const DEFAULT_PIN_TOOLTIP_KEY = 'p';
+
 export enum DashboardCursorSync {
 	Crosshair,
 	None,
@@ -34,11 +37,20 @@ export interface TooltipLayoutInfo {
 	height: number;
 }
 
+export interface TooltipSyncMetadata {
+	yAxisUnit?: string;
+}
+
 export interface TooltipPluginProps {
 	config: UPlotConfigBuilder;
 	canPinTooltip?: boolean;
+	/** Key that pins the tooltip while hovering. Defaults to DEFAULT_PIN_TOOLTIP_KEY ('l'). */
+	pinKey?: string;
+	/** Called when the user clicks the uPlot overlay. Receives resolved click data. */
+	onClick?: (clickData: TooltipClickData) => void;
 	syncMode?: DashboardCursorSync;
 	syncKey?: string;
+	syncMetadata?: TooltipSyncMetadata;
 	render: (args: TooltipRenderArgs) => ReactNode;
 	pinnedTooltipElement?: (clickData: TooltipClickData) => ReactNode;
 	maxWidth?: number;

frontend/src/lib/uPlotV2/plugins/TooltipPlugin/utils.ts

@@ -1,4 +1,11 @@
-import { TOOLTIP_OFFSET, TooltipLayoutInfo, TooltipViewState } from './types';
+import { getFocusedSeriesAtPosition } from 'lib/uPlotLib/plugins/onClickPlugin';
+
+import {
+	TOOLTIP_OFFSET,
+	TooltipClickData,
+	TooltipLayoutInfo,
+	TooltipViewState,
+} from './types';
 
 export function isPlotInViewport(
 	rect: uPlot.BBox,
@@ -158,3 +165,40 @@ export function createLayoutObserver(
 	};
 	return layout;
 }
+
+/**
+ * Resolves a TooltipClickData snapshot from a MouseEvent (real or synthetic)
+ * and the current uPlot instance. Shared by the overlay click handler and the
+ * keyboard-pin handler (which synthesises an event from the cursor position).
+ */
+export function buildClickData(
+	event: MouseEvent,
+	plot: uPlot,
+): TooltipClickData {
+	const xValue = plot.posToVal(event.offsetX, 'x');
+	const yValue = plot.posToVal(event.offsetY, 'y');
+	const focusedSeries = getFocusedSeriesAtPosition(event, plot);
+
+	const dataIndex = plot.posToIdx(event.offsetX);
+	let clickedDataTimestamp = xValue;
+	const xSeriesData = plot.data[0];
+	if (
+		xSeriesData &&
+		dataIndex >= 0 &&
+		dataIndex < xSeriesData.length &&
+		xSeriesData[dataIndex] !== undefined
+	) {
+		clickedDataTimestamp = xSeriesData[dataIndex];
+	}
+
+	return {
+		xValue,
+		yValue,
+		focusedSeries,
+		clickedDataTimestamp,
+		mouseX: event.offsetX,
+		mouseY: event.offsetY,
+		absoluteMouseX: event.clientX,
+		absoluteMouseY: event.clientY,
+	};
+}

frontend/src/lib/uPlotV2/plugins/__tests__/TooltipPlugin.test.ts

@@ -7,7 +7,10 @@ import type uPlot from 'uplot';
 import { TooltipRenderArgs } from '../../components/types';
 import { UPlotConfigBuilder } from '../../config/UPlotConfigBuilder';
 import TooltipPlugin from '../TooltipPlugin/TooltipPlugin';
-import { DashboardCursorSync } from '../TooltipPlugin/types';
+import {
+	DashboardCursorSync,
+	DEFAULT_PIN_TOOLTIP_KEY,
+} from '../TooltipPlugin/types';
 
 // Avoid depending on the full uPlot + onClickPlugin behaviour in these tests.
 // We only care that pinning logic runs without throwing, not which series is focused.
@@ -60,7 +63,7 @@ function getHandler(config: ConfigMock, hookName: string): HookHandler {
 function createFakePlot(): {
 	over: HTMLDivElement;
 	setCursor: jest.Mock<void, [uPlot.Cursor]>;
-	cursor: { event: Record<string, unknown> };
+	cursor: { event: Record<string, unknown>; left: number; top: number };
 	posToVal: jest.Mock<number, [value: number]>;
 	posToIdx: jest.Mock<number, []>;
 	data: [number[], number[]];
@@ -71,7 +74,9 @@ function createFakePlot(): {
 	return {
 		over,
 		setCursor: jest.fn(),
-		cursor: { event: {} },
+		// left / top are set to valid values so keyboard-pin tests do not
+		// hit the "cursor off-screen" guard inside handleKeyDown.
+		cursor: { event: {}, left: 50, top: 50 },
 		// In real uPlot these map overlay coordinates to data-space values.
 		posToVal: jest.fn((value: number) => value),
 		posToIdx: jest.fn(() => 0),
@@ -245,18 +250,21 @@ describe('TooltipPlugin', () => {
 	// ---- Pin behaviour ----------------------------------------------------------
 
 	describe('pin behaviour', () => {
-		it('pins the tooltip when canPinTooltip is true and overlay is clicked', () => {
+		it('pins the tooltip when canPinTooltip is true and the pinKey is pressed while hovering', () => {
 			const config = createConfigMock();
 
-			const fakePlot = renderAndActivateHover(config, undefined, {
-				canPinTooltip: true,
-			});
+			renderAndActivateHover(config, undefined, { canPinTooltip: true });
 
 			const container = screen.getByTestId('tooltip-plugin-container');
 			expect(container.classList.contains('pinned')).toBe(false);
 
 			act(() => {
-				fakePlot.over.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
 			});
 
 			return waitFor(() => {
@@ -272,7 +280,7 @@ describe('TooltipPlugin', () => {
 				React.createElement('div', null, 'pinned-tooltip'),
 			);
 
-			const fakePlot = renderAndActivateHover(
+			renderAndActivateHover(
 				config,
 				() => React.createElement('div', null, 'hover-tooltip'),
 				{
@@ -284,7 +292,12 @@ describe('TooltipPlugin', () => {
 			expect(screen.getByText('hover-tooltip')).toBeInTheDocument();
 
 			act(() => {
-				fakePlot.over.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
 			});
 
 			await waitFor(() => {
@@ -318,9 +331,14 @@ describe('TooltipPlugin', () => {
 				getHandler(config, 'setSeries')(fakePlot, 1, { focus: true });
 			});
 
-			// Pin the tooltip.
+			// Pin the tooltip via the keyboard shortcut.
 			act(() => {
-				fakePlot.over.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
 			});
 
 			// Wait until the tooltip is actually pinned (pointer events enabled)
@@ -369,9 +387,14 @@ describe('TooltipPlugin', () => {
 				jest.runAllTimers();
 			});
 
-			// Pin.
+			// Pin via keyboard.
 			act(() => {
-				fakePlot.over.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
 				jest.runAllTimers();
 			});
 
@@ -417,8 +440,14 @@ describe('TooltipPlugin', () => {
 				jest.runAllTimers();
 			});
 
+			// Pin via keyboard.
 			act(() => {
-				fakePlot.over.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
 				jest.runAllTimers();
 			});
 
@@ -446,7 +475,7 @@ describe('TooltipPlugin', () => {
 			jest.useRealTimers();
 		});
 
-		it('unpins the tooltip on outside keydown', async () => {
+		it('unpins the tooltip when Escape is pressed while pinned', async () => {
 			jest.useFakeTimers();
 			const config = createConfigMock();
 
@@ -467,8 +496,14 @@ describe('TooltipPlugin', () => {
 				jest.runAllTimers();
 			});
 
+			// Pin via keyboard.
 			act(() => {
-				fakePlot.over.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
 				jest.runAllTimers();
 			});
 
@@ -478,7 +513,7 @@ describe('TooltipPlugin', () => {
 					?.classList.contains('pinned'),
 			).toBe(true);
 
-			// Press a key outside the tooltip.
+			// Press Escape to release.
 			act(() => {
 				document.body.dispatchEvent(
 					new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }),
@@ -496,6 +531,277 @@ describe('TooltipPlugin', () => {
 
 			jest.useRealTimers();
 		});
+
+		it('unpins the tooltip when the pin key is pressed a second time (toggle off)', async () => {
+			jest.useFakeTimers();
+			const config = createConfigMock();
+
+			renderAndActivateHover(config, undefined, { canPinTooltip: true });
+			jest.runAllTimers();
+
+			// First press — pin.
+			act(() => {
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
+				jest.runAllTimers();
+			});
+
+			await waitFor(() => {
+				expect(
+					screen
+						.getByTestId('tooltip-plugin-container')
+						.classList.contains('pinned'),
+				).toBe(true);
+			});
+
+			// Second press — unpin (toggle off).
+			act(() => {
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
+				jest.runAllTimers();
+			});
+
+			await waitFor(() => {
+				const container = screen.getByTestId('tooltip-plugin-container');
+				expect(container.classList.contains('pinned')).toBe(false);
+			});
+
+			jest.useRealTimers();
+		});
+
+		it('does not unpin on Escape when tooltip is not pinned', () => {
+			const config = createConfigMock();
+			renderAndActivateHover(config, undefined, { canPinTooltip: true });
+
+			// Escape without pinning first — should be a no-op.
+			act(() => {
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }),
+				);
+			});
+
+			const container = screen.getByTestId('tooltip-plugin-container');
+			// Tooltip should still be hovering (visible), not dismissed.
+			expect(container.classList.contains('visible')).toBe(true);
+			expect(container.classList.contains('pinned')).toBe(false);
+		});
+
+		it('does not unpin on arbitrary keys that are not Escape or the pin key', async () => {
+			jest.useFakeTimers();
+			const config = createConfigMock();
+
+			renderAndActivateHover(config, undefined, { canPinTooltip: true });
+			jest.runAllTimers();
+
+			// Pin.
+			act(() => {
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
+				jest.runAllTimers();
+			});
+
+			await waitFor(() => {
+				expect(
+					screen
+						.getByTestId('tooltip-plugin-container')
+						.classList.contains('pinned'),
+				).toBe(true);
+			});
+
+			// Arrow key — should NOT unpin.
+			act(() => {
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }),
+				);
+				jest.runAllTimers();
+			});
+
+			await waitFor(() => {
+				expect(
+					screen
+						.getByTestId('tooltip-plugin-container')
+						.classList.contains('pinned'),
+				).toBe(true);
+			});
+
+			jest.useRealTimers();
+		});
+	});
+
+	// ---- Keyboard pin edge cases ------------------------------------------------
+
+	describe('keyboard pin edge cases', () => {
+		it('does not pin when cursor coordinates are negative (cursor off-screen)', () => {
+			const config = createConfigMock();
+
+			render(
+				React.createElement(TooltipPlugin, {
+					config,
+					render: () => React.createElement('div', null, 'tooltip-body'),
+					syncMode: DashboardCursorSync.None,
+					canPinTooltip: true,
+				}),
+			);
+
+			// Negative cursor coords — handleKeyDown bails out before pinning.
+			const fakePlot = {
+				...createFakePlot(),
+				cursor: { event: {}, left: -1, top: -1 },
+			};
+
+			act(() => {
+				getHandler(config, 'init')(fakePlot);
+				getHandler(config, 'setSeries')(fakePlot, 1, { focus: true });
+			});
+
+			act(() => {
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
+			});
+
+			const container = screen.getByTestId('tooltip-plugin-container');
+			expect(container.classList.contains('pinned')).toBe(false);
+		});
+
+		it('does not pin when hover is not active', () => {
+			const config = createConfigMock();
+
+			render(
+				React.createElement(TooltipPlugin, {
+					config,
+					render: () => React.createElement('div', null, 'tooltip-body'),
+					syncMode: DashboardCursorSync.None,
+					canPinTooltip: true,
+				}),
+			);
+
+			const fakePlot = createFakePlot();
+
+			act(() => {
+				// Initialise the plot but do NOT call setSeries – hoverActive stays false.
+				getHandler(config, 'init')(fakePlot);
+			});
+
+			act(() => {
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
+			});
+
+			// The container exists once the plot is initialised, but it should
+			// be hidden and not pinned since hover was never activated.
+			const container = screen.getByTestId('tooltip-plugin-container');
+			expect(container.classList.contains('pinned')).toBe(false);
+			expect(container.classList.contains('visible')).toBe(false);
+		});
+
+		it('ignores other keys and only pins on the configured pinKey', async () => {
+			const config = createConfigMock();
+
+			renderAndActivateHover(config, undefined, {
+				canPinTooltip: true,
+				pinKey: 'p',
+			});
+
+			// Default key 'l' should NOT pin when pinKey is 'p'.
+			act(() => {
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', {
+						key: DEFAULT_PIN_TOOLTIP_KEY,
+						bubbles: true,
+					}),
+				);
+			});
+
+			await waitFor(() => {
+				expect(
+					screen
+						.getByTestId('tooltip-plugin-container')
+						.classList.contains('pinned'),
+				).toBe(false);
+			});
+
+			// Custom pin key 'p' SHOULD pin.
+			act(() => {
+				document.body.dispatchEvent(
+					new KeyboardEvent('keydown', { key: 'p', bubbles: true }),
+				);
+			});
+
+			await waitFor(() => {
+				expect(
+					screen
+						.getByTestId('tooltip-plugin-container')
+						.classList.contains('pinned'),
+				).toBe(true);
+			});
+		});
+
+		it('does not register a keydown listener when canPinTooltip is false', () => {
+			const config = createConfigMock();
+			const addSpy = jest.spyOn(document, 'addEventListener');
+
+			render(
+				React.createElement(TooltipPlugin, {
+					config,
+					render: () => null,
+					syncMode: DashboardCursorSync.None,
+					canPinTooltip: false,
+				}),
+			);
+
+			const keydownCalls = addSpy.mock.calls.filter(
+				([type]) => type === 'keydown',
+			);
+			expect(keydownCalls).toHaveLength(0);
+		});
+
+		it('removes the keydown pin listener on unmount', () => {
+			const config = createConfigMock();
+			const addSpy = jest.spyOn(document, 'addEventListener');
+			const removeSpy = jest.spyOn(document, 'removeEventListener');
+
+			const { unmount } = render(
+				React.createElement(TooltipPlugin, {
+					config,
+					render: () => null,
+					syncMode: DashboardCursorSync.None,
+					canPinTooltip: true,
+				}),
+			);
+
+			const pinListenerCall = addSpy.mock.calls.find(
+				([type]) => type === 'keydown',
+			);
+			expect(pinListenerCall).toBeDefined();
+			if (!pinListenerCall) {
+				return;
+			}
+			const [, pinListener, pinOptions] = pinListenerCall;
+
+			unmount();
+
+			expect(removeSpy).toHaveBeenCalledWith('keydown', pinListener, pinOptions);
+		});
 	});
 
 	// ---- Cursor sync ------------------------------------------------------------
@@ -516,7 +822,7 @@ describe('TooltipPlugin', () => {
 			);
 
 			expect(setCursorSpy).toHaveBeenCalledWith({
-				sync: { key: 'dashboard-sync', scales: ['x', null] },
+				sync: { key: 'dashboard-sync', scales: ['x', 'y'] },
 			});
 		});