Skip to content

feat: Add internal hover debounce to core chart - #283

Open
ryugaraj wants to merge 1 commit into
cloudscape-design:mainfrom
ryugaraj:feat/hover-debounce
Open

ryugaraj wants to merge 1 commit into
cloudscape-design:mainfrom
ryugaraj:feat/hover-debounce

Conversation

@ryugaraj

@ryugaraj ryugaraj commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Description

In dense charts, series highlight, legend highlight, legend scroll-into-view and the tooltip all react to every pointer move, which causes a lot of motion. The existing tooltip.debounce only delays the tooltip.

This adds an internal hoverDebounce prop to core chart (a number in ms, or true for 150ms):

  • At once: the hovered series and its legend item highlight, the cursor line and point markers show, and onHighlight / onLegendItemHighlight fire (once per target), so charts synced through these events follow straight away.
  • After the delay: dimming the other series and legend items, the first time the chart dims. Once it's dimmed, moving to another series swaps the highlight at once. Column series dim at once, because a hovered column's own hover state is hard to see.
  • After the delay: the tooltip and the legend item tooltip. tooltip.debounce is ignored while hoverDebounce is set, so the delays don't stack, and it's marked for removal.
  • Once the pointer rests: the legend scrolls the highlighted item into view only after the pointer has stopped moving for the delay.
  • No fade: undimming is instant.
  • Not delayed: keyboard navigation and legend item focus.

Details:

  • Public API. highlightItems, highlightChartPoint and highlightChartGroup follow the same model: the target lights up at once, and dimming and the tooltip follow after the delay. This lets a synced chart light the series together with the hovered chart and dim after the same delay. Without it, synced charts would dim at once while the hovered chart waits.
  • Delay scheduling. DebouncedCall (src/internal/utils/utils.ts) can now take a key: scheduling the key that is already pending keeps it instead of restarting the delay, flush() runs the pending call at once, and cancelPending() (renamed from cancelPrevious()) reports whether something was pending. Callers that don't pass a key behave as before.
  • Pinning is immediate. A click applies the pending hover first, so pinning works before the delay ends.
  • Cancellation. highlightActions, clearHighlightActions, highlightChartItems and the legend's clear-highlight cancel pending hovers at the top. Pointer, legend and API hovers replace each other's pending highlight through one scheduling method. A pending highlight is also dropped when the pointer leaves its target or enters the tooltip, on Escape, chart focus, visibility changes, zoom start and destroy. The previewed highlight is then restored, and onHighlight or onClearHighlight reports the result. A pending point or group is checked for visibility again when the delay ends.
  • Legend. The internal legend takes the tooltip delay and an optional getScrollIntoViewDelay callback, and doesn't know about the core's debounce.

Without hoverDebounce, behavior is unchanged. Like the zoom props, the prop lives in internal-interfaces.ts and isn't part of the public API, so the documenter snapshot doesn't change.

Related links, issue #, if available: n/a

How has this been tested?

  • Unit tests: 23 in src/core/__tests__/chart-core-hover-debounce.test.tsx, covering the instant highlight with the delayed dimming and tooltip, the immediate swap once dimmed, column and pie points, the 150ms default with tooltip.debounce ignored, a zero delay, moving into the tooltip, click to pin, the visibility re-check, the cancellation cases (pointer leave, Escape, chart focus, visibility change, zoom start), API highlights, and legend hover, leave, toggle, Escape and focus. 6 more in src/internal/utils/__tests__/utils.test.ts for DebouncedCall. Full unit suite: 617 passing.
  • Browser tests: 4 in test/functional/hover-debounce.test.ts, using real WebDriver mouse input against the core line chart page with a 1000ms delay. They check that the cursor shows at once while the tooltip waits, that the tooltip stays on the previous point until the pointer rests, that dimming waits when hovering a legend item, and the no-delay baseline. All functional tests pass with npm run test:functional.
  • Dev pages: the existing core pages (line, bar, dual-axis, legend, heatmap, solid gauge, zooming and boost) have a "Hover debounce (ms)" page setting, also readable from the hoverDebounce URL parameter, for example #/03-core/core-line-chart?hoverDebounce=150. The default is 0, which shows the current behavior.
  • Consumer check: an earlier version was also tried in a consumer's Storybook and local dev server via a patched build.
Review checklist

The following items are to be evaluated by the author(s) and the reviewer(s).

Correctness

  • Changes include appropriate documentation updates.
  • Changes are backward-compatible if not indicated, see CONTRIBUTING.md.
  • Changes do not include unsupported browser features, see CONTRIBUTING.md.
  • Changes were manually tested for accessibility, see accessibility guidelines.

Security

Testing

  • Changes are covered with new/existing unit tests?
  • Changes are covered with new/existing integration tests?

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Screen.Recording.2026-11-18.at.17.02.59.mov

@ryugaraj
ryugaraj requested a review from a team as a code owner November 11, 2026 15:54
@ryugaraj
ryugaraj requested review from taheramr and removed request for a team November 11, 2026 15:54
@pan-kot
pan-kot requested review from pan-kot and a balanced review from Copilot November 11, 2026 16:20
@pan-kot

pan-kot commented Nov 12, 2026

Copy link
Copy Markdown
Member

I ran my review agent on the PR, here are its findings that I deem relevant:

  1. Two debounce mechanisms exist at the same time - we need a strategy to sunset the old one.

  2. Cancellation is sprinkled over 15 call sites. cancelPendingHovers()/legendItemHover.cancel() appear in onDismissTooltip, hideTooltip, four public API methods, five navigation handlers, two legend callbacks, destroy, and clearHover. Every one of those paths ends in highlightActions, clearHighlightActions or highlightChartItems. Put the cancel at the top of those three funnels and most call sites go away. The scheduler's own flush() clears pending before it applies, so the funnel's cancel is a no-op for the hover it is applying. Keep an explicit cancel only where a path skips the funnels (onDismissHoverTooltip when nothing is visible, destroy). Fewer sites means fewer paths to miss later.

  3. Redundant tests. "hides the datapoint cursor when hover is lost" (97) and "drops a pending highlight when hover is lost" (172) are the same scenario with different assertions; merge. "highlights immediately when hoverDebounce is not set" (221) is what every other test in the repo already exercises. "restarts the delay when the target changes" (125) and "keeps the current highlight until the next target settles" (155) overlap. 393 lines should be about 300.

  4. hoverDelay leaks into the internal legend only to set tooltipShowDelay and force scrollDelay to 0. Passing the two derived values (or just the tooltip delay) keeps the internal component ignorant of the core's debounce.

  5. onItemHighlightEnter(item, detail?: { pointer }). The internal legend always passes detail; make it required and drop the ?..

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Incomplete hover cancellation and timer cleanup allow delayed tooltips and highlights to appear after Escape, legend interactions, or delay changes, while canceled or hidden targets can leave stale cursor previews.

6 open issues
What changed in this PR

Adds internal hover debouncing to the core chart to coordinate highlights, legend scrolling, and tooltips in dense charts while keeping cursor previews immediate.

Changes:

  • Introduces a shared scheduler implementation for delayed point, group, and legend hover effects.
  • Adds cancellation, click-to-pin handling, and visibility checks for pending targets.
  • Adds unit tests, browser tests, and a configurable dense-chart demo.
File Description
test/​functional/​hover-debounce.test.ts Adds browser coverage for delayed and immediate hover behavior.
src/​internal/​components/​chart-legend/​index.tsx Configures tooltip and scroll timing and distinguishes pointer hover.
src/​core/​internal-interfaces.ts Defines the internal hoverDebounce prop.
src/​core/​components/​core-legend.tsx Routes legend pointer highlights through the scheduler.
src/​core/​chart-core.tsx Wires hover delay into chart settings, legends, and tooltips.
src/​core/​chart-api/​index.tsx Coordinates legend scheduling, cursor previews, and cancellation.
src/​core/​chart-api/​hover-scheduler.ts Adds reusable target-aware hover scheduling.
src/​core/​chart-api/​chart-extra-tooltip.tsx Separates cursor previews from tooltip anchor updates.
src/​core/​chart-api/​chart-extra-pointer.tsx Schedules pointer targets and flushes pending hover on click.
src/​core/​chart-api/​chart-extra-context.tsx Adds the hover-delay setting and default.
src/​core/​__tests__/​common.tsx Extends test helpers to accept internal hover props.
src/​core/​__tests__/​chart-core-hover-debounce.test.tsx Covers timing, previews, cancellation, and visibility checks.
pages/​03-core/​hover-debounce.page.tsx Adds a dense-chart demo with adjustable delay.

Review effort: Balanced

Comment thread src/core/chart-api/index.tsx Resolved
Comment thread src/core/chart-api/index.tsx Resolved
Comment thread src/core/chart-api/index.tsx Resolved
@ryugaraj
ryugaraj force-pushed the feat/hover-debounce branch from d12e9a7 to 9c26861 Compare November 12, 2026 14:04
@ryugaraj

ryugaraj commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor Author

Thanks for the review. All points are addressed in 9c26861:

  1. Two debounce mechanisms. hoverDebounce supersedes tooltip.debounce. While hoverDebounce is set, tooltip.debounce is ignored, so the two never stack. Code comments on InternalHoverProps, TooltipOptions.debounce and in chart-core.tsx record this and the plan to remove tooltip.debounce. CloudWatch is planning to drop tooltip.debounce and use hoverDebounce: 300 for all charts and sizes after this change is merged. Once that's adopted, we'd propose:

    • making hoverDebounce public, or the default;
    • deprecating tooltip.debounce;
    • removing it after consumers (CloudWatch) move over.

    We're happy to align the true default (300ms here vs 200ms for tooltip.debounce) to whichever you prefer.

  2. Cancellation. It now lives in the three funnels: highlightActions, clearHighlightActions and highlightChartItems. Explicit cancels remain only where a path skips them: Escape with nothing visible (navigation and document handlers), visibility changes, and destroy.

  3. Tests. I merged the two hover-lost tests and the restart/keep pair, and dropped the no-delay test. The file is still about 440 lines because it now also covers the six Copilot findings (23 tests in total).

  4. Legend. The internal legend now takes plain tooltipShowDelay and scrollIntoViewDelay props and knows nothing about the core debounce.

  5. detail. It's now required.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

}
};

private applyHover = (target: PointerHoverTarget) => {
Comment thread src/core/chart-api/index.tsx Resolved
Comment thread src/core/chart-api/index.tsx Outdated
if (this.chartExtraPointer.cancelPendingHover()) {
this.chartExtraTooltip.restoreCursor();
}
this.legendItemHover.cancel();
Comment thread src/core/chart-api/index.tsx Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved hover scheduling and state issues can show stale tooltips, highlight items after legend teardown, cancel newer cross-legend hovers, and reset cursor previews on redraw.

6 open issues
2 resolved since last review

Review effort: Balanced

Comment on lines +99 to +102
public showCursor(point: null | Highcharts.Point, group: readonly Highcharts.Point[]) {
if (!this.tooltipLock && this.chartType === "cartesian") {
this.createCursor(point, group);
}
Comment thread src/core/chart-api/index.tsx Outdated
};
public onLeaveLegendItem = () => this.legendItemHover.cancel();
public onClearChartItemsHighlight = () => {
this.legendItemHover.cancel();
Comment thread src/core/chart-api/index.tsx Outdated
Comment on lines +508 to +510
if (!keepLegendHover) {
this.legendItemHover.cancel();
}
},
};
}, []);
useEffect(() => cancelTooltip, [cancelTooltip]);
labels: ChartLabels;
getItemOptions?: CoreChartProps.GetItemOptions;
zoomEnabled: boolean;
hoverDelay: number;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it deliberate that the behaviour only applies for pointer hover but not for keyboard highlight?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, deliberate. The delay filters the in-between targets a pointer passes over while sweeping a dense chart. A keyboard step goes straight to one intended target, so it is not really an issue there. Do you think we should try to debounce keyboard navigation as well?

@pan-kot pan-kot Nov 17, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that keyboard interactions are included - I believe we need to come up with a better var name, as "hover" implies pointer interactions.

I am thinking of some abstract one like debounce or effectsDebounce. One advantage here is that we can type it as number now, but later expand if we need more fine-grained configuration, like debounce: { hover: 300, keyboard: 200 } etc.

What do you think?

Comment thread src/core/chart-api/hover-scheduler.ts Outdated

import { DebouncedCall } from "../../internal/utils/utils";

export class HoverScheduler<Target> {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: The class looks very abstract as Target is generic - it has no logic coupled to the hover or chart etc. I recommend calling it differently, maybe DebounceScheduler etc. - or see if it can be merged with DebouncedCall.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Merging it with DebouncedCall.

Comment thread pages/03-core/hover-debounce.page.tsx Outdated
@@ -0,0 +1,86 @@
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page does not feature anything new but the hover. I recommend to instead add it as settings to existing core chart test pages, where it makes sense. This will allow to see how it works in practice on the variety of different chart types and settings combinations - including core-specific chart types like heapmap or gauge.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Makes sense, I will add it to the existing pages.

@ryugaraj
ryugaraj requested a review from pan-kot November 13, 2026 10:49
@ryugaraj
ryugaraj force-pushed the feat/hover-debounce branch from 5066937 to 19b5ab6 Compare November 13, 2026 11:10
@github-actions
github-actions Bot temporarily deployed to fork-dev-pages November 13, 2026 15:42 Inactive
@codecov

codecov Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 97.93103% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.43%. Comparing base (31ed247) to head (7369812).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
src/core/chart-api/chart-extra-pointer.tsx 96.15% 1 Missing ⚠️
src/core/chart-api/index.tsx 98.21% 1 Missing ⚠️
src/internal/utils/utils.ts 95.23% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #283      +/-   ##
==========================================
- Coverage   93.81%   92.43%   -1.38%     
==========================================
  Files          64       64              
  Lines        3445     2923     -522     
  Branches     1092      894     -198     
==========================================
- Hits         3232     2702     -530     
+ Misses        213      181      -32     
- Partials        0       40      +40     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment on lines +78 to +80
if (this.hover.cancelPrevious()) {
this.handlers.onHoverPreviewCancel();
}
Comment thread src/core/chart-api/index.tsx Outdated
}

private applyActivatedTarget(target: PointerHoverTarget) {
this.focusHighlight.cancelPrevious();
return {
showTooltip(itemId: string) {
control.call(() => setTooltipItemId(itemId), TOOLTIP_SHOW_DELAY);
control.call(() => setTooltipItemId(itemId), tooltipShowDelayRef.current);
showTooltip(item.id);
},
onMouseLeave: () => {
onItemHoverLeave?.();
this.tooltipHovered = true;
this.hoveredPoint = null;
this.hoveredGroup = null;
if (this.hover.cancelPrevious()) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice thinking! I love that we cancel next hover when the cursor goes inside the tooltip 👍

Comment thread src/internal/utils/utils.ts Outdated
pending?.callback();
};

public cancelPrevious(): boolean {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we rename this to cancelPending for better clearity?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good, renaming!

Comment thread src/core/chart-core.tsx
if (tooltipState.visible && !tooltipState.pinned) {
api.hideTooltip();
if (event.keyCode === KeyCode.escape) {
api.cancelPendingHovers();

@pan-kot pan-kot Nov 17, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why do we need this change? I removed that locally and noticed no effect on the UX.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can see the difference on a long debounce, if you hover on a datapoint and press Esc before the debounce settles, it will still show the tooltip while. With this change it cancels it so the tooltip is not shown if the debounce was interrupted with an Esc.

@ryugaraj
ryugaraj force-pushed the feat/hover-debounce branch from 7369812 to b9c0950 Compare November 18, 2026 16:27
In dense charts, series highlight, legend highlight, legend
scroll-into-view and the tooltip all react to every pointer move, which
causes a lot of motion. The existing tooltip.debounce only delays the
tooltip.

This adds an internal hoverDebounce prop to core chart (a number in ms,
or true for 150ms). The hovered series and its legend item highlight as
soon as the pointer reaches them, and onHighlight and
onLegendItemHighlight fire at once. Dimming the other series and legend
items waits for the delay when nothing is dimmed yet; once they are
dimmed, moving to another target swaps the highlight at once. Column
series dim at once, as their hover state alone is hard to see. The
tooltip, including the legend item tooltip, waits for the delay, and the
legend scrolls the highlighted item into view only after the pointer has
rested for the delay. Undimming has no fade.

highlightItems, highlightChartPoint and highlightChartGroup from the
public API follow the same model, so a chart that syncs highlights
through onHighlight lights the same series at once and dims after the
delay. Keyboard navigation and legend item focus are not delayed.

A pending hover is dropped when the pointer leaves its target or enters
the tooltip, on Escape, chart focus, visibility changes, zoom start and
destroy, and is replaced by a newer pointer, legend or API hover. The
previewed highlight is then restored, and onHighlight or onClearHighlight
reports the result. A click applies the pending hover first, so pinning
doesn't wait, and a pending point or group is checked for visibility
again when the delay ends.

DebouncedCall can now take a key: scheduling the key that is already
pending keeps it, flush() runs the pending call, and cancelPending()
(renamed from cancelPrevious()) reports whether something was pending.
tooltip.debounce is ignored while hoverDebounce is set, and is planned
for removal. The core dev pages get a "Hover debounce (ms)" setting.
Without hoverDebounce, the behavior is unchanged.
@ryugaraj
ryugaraj force-pushed the feat/hover-debounce branch from b9c0950 to 004d36d Compare November 18, 2026 16:45

This branch was successfully deployed

1 active (outdated) deployment
fork-dev-pages — 73698127 Deployed Nov 17, 2026 by github-actions[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants