From 34572a15e68029ebf892576e1f878463eca20b48 Mon Sep 17 00:00:00 2001 From: Guilherme Lopes Date: Tue, 27 Jan 2026 18:25:36 -0300 Subject: [PATCH] AG-15310 - [tooltip] - Added Tooltip Switch Delay (#12985) * AG-15310 - [tooltip] - Added Tooltip Switch Delay * docs cleanup * docs cleanup * docs cleanup --- .../grid-options/properties.json | 6 ++++ .../_examples/show-hide-delay/main.ts | 1 + .../src/content/docs/tooltips/index.mdoc | 12 +++++++- .../src/lib/ag-grid-angular.component.ts | 7 +++++ .../src/agStack/interfaces/baseProperties.ts | 1 + .../src/agStack/interfaces/iTooltip.ts | 1 + .../tooltip/baseTooltipStateManager.ts | 29 ++++++++++--------- .../src/entities/gridOptions.ts | 8 +++++ .../src/gridOptionsDefault.ts | 1 + .../ag-grid-community/src/propertyKeys.ts | 1 + .../rules/gridOptionsValidations.ts | 8 +++++ packages/ag-grid-vue3/src/components/utils.ts | 8 +++++ 12 files changed, 68 insertions(+), 15 deletions(-) diff --git a/documentation/ag-grid-docs/src/content/api-documentation/grid-options/properties.json b/documentation/ag-grid-docs/src/content/api-documentation/grid-options/properties.json index af63869dea2..dd72b9c54c8 100644 --- a/documentation/ag-grid-docs/src/content/api-documentation/grid-options/properties.json +++ b/documentation/ag-grid-docs/src/content/api-documentation/grid-options/properties.json @@ -2065,6 +2065,12 @@ "url": "./tooltips/#show-and-hide-delay" } }, + "tooltipSwitchShowDelay": { + "more": { + "name": "Tooltip Show and Hide Delay", + "url": "./tooltips/#show-and-hide-delay" + } + }, "tooltipHideDelay": { "more": { "name": "Tooltip Show and Hide Delay", diff --git a/documentation/ag-grid-docs/src/content/docs/tooltips/_examples/show-hide-delay/main.ts b/documentation/ag-grid-docs/src/content/docs/tooltips/_examples/show-hide-delay/main.ts index 5ca81ebe7cf..aa697316e0d 100644 --- a/documentation/ag-grid-docs/src/content/docs/tooltips/_examples/show-hide-delay/main.ts +++ b/documentation/ag-grid-docs/src/content/docs/tooltips/_examples/show-hide-delay/main.ts @@ -46,6 +46,7 @@ const gridOptions: GridOptions = { minWidth: 100, }, tooltipShowDelay: 0, + tooltipSwitchShowDelay: 1000, tooltipHideDelay: 2000, columnDefs: columnDefs, }; diff --git a/documentation/ag-grid-docs/src/content/docs/tooltips/index.mdoc b/documentation/ag-grid-docs/src/content/docs/tooltips/index.mdoc index 74983a17a33..647174e5899 100644 --- a/documentation/ag-grid-docs/src/content/docs/tooltips/index.mdoc +++ b/documentation/ag-grid-docs/src/content/docs/tooltips/index.mdoc @@ -18,7 +18,17 @@ It's possible to configure tooltips to show only when the items hovered are trun ## Show and Hide Delay -Tooltips show after 2 seconds and hide after 10 seconds. Set `tooltipShowDelay` and `tooltipHideDelay` to override these values. The example below has `tooltipShowDelay=0` (shows immediately) and `tooltipHideDelay=2000` (hides in 2,000 milliseconds, or 2 seconds). +By default, tooltips show after 2 seconds and hide after 10 seconds. These delays can be configured in milliseconds: + +{% apiDocumentation source="grid-options/properties.json" section="tooltips" names=["tooltipShowDelay", "tooltipSwitchShowDelay", "tooltipHideDelay"] /%} + +```{% frameworkTransform=true %} +const gridOptions = { + tooltipShowDelay: 0, + tooltipSwitchShowDelay: 1000, + tooltipHideDelay: 2000, +}; +``` {% gridExampleRunner title="Show Hide Delay" name="show-hide-delay" /%} diff --git a/packages/ag-grid-angular/projects/ag-grid-angular/src/lib/ag-grid-angular.component.ts b/packages/ag-grid-angular/projects/ag-grid-angular/src/lib/ag-grid-angular.component.ts index 990dc1c8888..112e7f0e520 100644 --- a/packages/ag-grid-angular/projects/ag-grid-angular/src/lib/ag-grid-angular.component.ts +++ b/packages/ag-grid-angular/projects/ag-grid-angular/src/lib/ag-grid-angular.component.ts @@ -460,6 +460,13 @@ export class AgGridAngular = ColDef { getLocation?(): TLocation | 'UNKNOWN'; getTooltipShowDelayOverride?(): number; + getTooltipSwitchShowDelayOverride?(): number; getTooltipHideDelayOverride?(): number; shouldDisplayTooltip?(): boolean; diff --git a/packages/ag-grid-community/src/agStack/tooltip/baseTooltipStateManager.ts b/packages/ag-grid-community/src/agStack/tooltip/baseTooltipStateManager.ts index f1abebeaba1..cb76691bfce 100644 --- a/packages/ag-grid-community/src/agStack/tooltip/baseTooltipStateManager.ts +++ b/packages/ag-grid-community/src/agStack/tooltip/baseTooltipStateManager.ts @@ -20,7 +20,7 @@ export enum TooltipTrigger { FOCUS, } -const SHOW_QUICK_TOOLTIP_DIFF = 1000; +const SHOW_SWITCH_TOOLTIP_DIFF = 1000; const FADE_OUT_TOOLTIP_TIMEOUT = 1000; const INTERACTIVE_HIDE_DELAY = 100; @@ -131,19 +131,18 @@ export abstract class BaseTooltipStateManager< } } - private getGridOptionsTooltipDelay(delayOption: 'tooltipShowDelay' | 'tooltipHideDelay'): number { + private getGridOptionsTooltipDelay( + delayOption: 'tooltipShowDelay' | 'tooltipHideDelay' | 'tooltipSwitchShowDelay' + ): number { const delay = this.gos.get(delayOption)!; return Math.max(200, delay); } - private getTooltipDelay(type: 'show' | 'hide'): number { - if (type === 'show') { - return ( - this.tooltipCtrl.getTooltipShowDelayOverride?.() ?? this.getGridOptionsTooltipDelay('tooltipShowDelay') - ); - } - - return this.tooltipCtrl.getTooltipHideDelayOverride?.() ?? this.getGridOptionsTooltipDelay('tooltipHideDelay'); + private getTooltipDelay(type: 'Show' | 'Hide' | 'SwitchShow'): number { + return ( + this.tooltipCtrl[`getTooltip${type}DelayOverride`]?.() ?? + this.getGridOptionsTooltipDelay(`tooltip${type}Delay`) + ); } public override destroy(): void { @@ -252,10 +251,12 @@ export abstract class BaseTooltipStateManager< } // if we are showing the tooltip because of focus, no delay at all - // if another tooltip was hidden very recently, we only wait 200ms to show, not the normal waiting time + // if another tooltip was hidden very recently, use the switch show delay instead of the normal delay let delay = 0; if (mouseEvent) { - delay = this.isLastTooltipHiddenRecently() ? 200 : this.getTooltipDelay('show'); + delay = this.isLastTooltipHiddenRecently() + ? this.getTooltipDelay('SwitchShow') + : this.getTooltipDelay('Show'); } this.lastMouseEvent = mouseEvent || null; @@ -269,7 +270,7 @@ export abstract class BaseTooltipStateManager< const now = Date.now(); const then = lastTooltipHideTime; - return now - then < SHOW_QUICK_TOOLTIP_DIFF; + return now - then < SHOW_SWITCH_TOOLTIP_DIFF; } private setToDoNothing(fromHideTooltip?: boolean): void { @@ -544,7 +545,7 @@ export abstract class BaseTooltipStateManager< private startHideTimeout(): void { this.clearHideTimeout(); - this.hideTooltipTimeoutId = window.setTimeout(this.hideTooltip.bind(this), this.getTooltipDelay('hide')); + this.hideTooltipTimeoutId = window.setTimeout(this.hideTooltip.bind(this), this.getTooltipDelay('Hide')); } private clearShowTimeout(): void { diff --git a/packages/ag-grid-community/src/entities/gridOptions.ts b/packages/ag-grid-community/src/entities/gridOptions.ts index 9b8b4504a84..3f3f6ff2566 100644 --- a/packages/ag-grid-community/src/entities/gridOptions.ts +++ b/packages/ag-grid-community/src/entities/gridOptions.ts @@ -273,6 +273,14 @@ export interface GridOptions { * @agModule `TooltipModule` */ tooltipShowDelay?: number; + /** + * The delay in milliseconds before a tooltip is shown when moving the pointer from one tooltip-enabled element to + * another while the previous tooltip is still visible or pending hide. + * **Note:** This property does not work if `enableBrowserTooltips` is `true`. + * @default 200 + * @agModule `TooltipModule` + */ + tooltipSwitchShowDelay?: number; /** * The delay in milliseconds that it takes for tooltips to hide once they have been displayed. * **Note:** This property does not work if `enableBrowserTooltips` is `true` and `tooltipHideTriggers` includes `timeout`. diff --git a/packages/ag-grid-community/src/gridOptionsDefault.ts b/packages/ag-grid-community/src/gridOptionsDefault.ts index df4a2b83f05..7c2272c3ab4 100644 --- a/packages/ag-grid-community/src/gridOptionsDefault.ts +++ b/packages/ag-grid-community/src/gridOptionsDefault.ts @@ -12,6 +12,7 @@ export const GRID_OPTION_DEFAULTS = { enableBrowserTooltips: false, tooltipTrigger: 'hover', tooltipShowDelay: 2000, + tooltipSwitchShowDelay: 200, tooltipHideDelay: 10000, tooltipMouseTrack: false, tooltipShowMode: 'standard', diff --git a/packages/ag-grid-community/src/propertyKeys.ts b/packages/ag-grid-community/src/propertyKeys.ts index e3eff0996c3..9f80e4acaf1 100644 --- a/packages/ag-grid-community/src/propertyKeys.ts +++ b/packages/ag-grid-community/src/propertyKeys.ts @@ -149,6 +149,7 @@ export const _NUMBER_GRID_OPTIONS: KeysWithType[] = [ 'maxBlocksInCache', 'maxConcurrentDatasourceRequests', 'tooltipShowDelay', + 'tooltipSwitchShowDelay', 'tooltipHideDelay', 'cacheOverflowSize', 'paginationPageSize', diff --git a/packages/ag-grid-community/src/validation/rules/gridOptionsValidations.ts b/packages/ag-grid-community/src/validation/rules/gridOptionsValidations.ts index 95a2fd0ea34..e305ecee2cb 100644 --- a/packages/ag-grid-community/src/validation/rules/gridOptionsValidations.ts +++ b/packages/ag-grid-community/src/validation/rules/gridOptionsValidations.ts @@ -457,6 +457,14 @@ const GRID_OPTION_VALIDATIONS: () => Validations = () => { return null; }, }, + tooltipSwitchShowDelay: { + validate: (options) => { + if (options.tooltipSwitchShowDelay && options.tooltipSwitchShowDelay < 0) { + return 'tooltipSwitchShowDelay should not be lower than 0'; + } + return null; + }, + }, treeData: { supportedRowModels: ['clientSide', 'serverSide'], validate: (options) => { diff --git a/packages/ag-grid-vue3/src/components/utils.ts b/packages/ag-grid-vue3/src/components/utils.ts index e1c0e85a711..5997b76f2f8 100644 --- a/packages/ag-grid-vue3/src/components/utils.ts +++ b/packages/ag-grid-vue3/src/components/utils.ts @@ -294,6 +294,13 @@ export interface Props { * @agModule `TooltipModule` */ tooltipShowDelay?: number, + /** The delay in milliseconds before a tooltip is shown when moving the pointer from one tooltip-enabled element to + * another while the previous tooltip is still visible or pending hide. + * **Note:** This property does not work if `enableBrowserTooltips` is `true`. + * @default 200 + * @agModule `TooltipModule` + */ + tooltipSwitchShowDelay?: number, /** The delay in milliseconds that it takes for tooltips to hide once they have been displayed. * **Note:** This property does not work if `enableBrowserTooltips` is `true` and `tooltipHideTriggers` includes `timeout`. * @default 10000 @@ -2004,6 +2011,7 @@ export function getProps() { enableBrowserTooltips: undefined, tooltipTrigger: undefined, tooltipShowDelay: undefined, + tooltipSwitchShowDelay: undefined, tooltipHideDelay: undefined, tooltipMouseTrack: undefined, tooltipShowMode: undefined,