feat: add enableDefaultTooltips config option (#9559)

This configuration option defines whether components will display default tooltips in specific cases. Default tooltips are generally recommended to cover accessibility standards and typically you would not need to modify this setting. However, in rare cases you may want to implement custom tooltip visualisation and turn off the default tooltips. To do so, set enableDefaultTooltips to false. Fixes: #9494
SAP · Aug 6, 2024 · a672788 · a672788
1 parent b3c38f8
commit a672788
Show file tree

Hide file tree

Showing 11 changed files with 151 additions and 7 deletions.
diff --git a/docs/2-advanced/01-configuration.md b/docs/2-advanced/01-configuration.md
@@ -17,6 +17,7 @@ There are several configuration settings that affect all UI5 Web Components glob
 | [formatSettings](#formatSettings)             | See the [Format settings](#formatSettings) section below                                                                                                                                                                                                                                       | `{}`                  | Allows to override locale-specific configuration                       | Date/time components (`ui5-date-picker`, etc.)                 |
 | [fetchDefaultLanguage](#fetchDefaultLanguage) | `true`, `false`                                                                                                                                                                                                                                                                                | `false`               | Whether to fetch assets even for the default language                  | Framework                                                      |
 | [defaultFontLoading](#defaultFontLoading) | `true`, `false`                                                                                                                                                                                                                                                                                | `true`               | Whether to fetch default font faces                  | Framework                                                      |
+| [enableDefaultTooltips](#enableDefaultTooltips) | `true`, `false`                                                                                                                                                                                                                                                                                | `true`               | Whether to display default tooltips                     | Components (Icon, Button, RatingIndicator, etc.)                                                      |
 | [timezone](#timezone)                         | `Asia/Tokyo`, `Pacific/Apia`, `Asia/Kolkata`, `Europe/Sofia` and etc.                                                                                                                                                                                                                          | Your local time zone. | Allows to override your local time zone.                               | Date/time components (`ui5-date-picker`, etc.)                 |
 | [themeRoot](#themeRoot)                       | String to a URL - see the [themeRoot](#themeRoot) section below                                                                                                                                                                                                                                | N/A                   | Allows to set a URL to a Theme-designer-created custom theme.          | All components                                                 |
 
@@ -233,6 +234,25 @@ Example:
 }
 </script>
 ```
+
+### enableDefaultTooltips
+<a name="enableDefaultTooltips"></a>
+
+This configuration option controls whether components will display default tooltips in specific cases.
+
+Default tooltips are generally recommended to cover accessibility standards and typically you would not need to modify this setting.
+However, in rare cases you may want to implement custom tooltip visualization and turn off the default tooltips.
+To do so, set `enableDefaultTooltips` to `false`.
+
+Example:
+```html
+<script data-ui5-config type="application/json">
+{
+	"enableDefaultTooltips": false
+}
+</script>
+```
+
 ### timezone
 <a name="timezone"></a>
 
@@ -349,6 +369,13 @@ import { getFetchDefaultLanguage, setFetchDefaultLanguage } from "@ui5/webcompon
 ```js
 import { getDefaultFontLoading, setDefaultFontLoading } from "@ui5/webcomponents-base/dist/config/Fonts.js";
 ```
+
+ - `enableDefaultTooltips`
+
+```js
+import { getEnableDefaultTooltips, setEnableDefaultTooltips } from "@ui5/webcomponents-base/dist/config/Tooltips.js";
+```
+
  - `timezone` - can only be set initially in the configuration script.
 
 ```js

diff --git a/packages/base/bundle.esm.js b/packages/base/bundle.esm.js
@@ -32,6 +32,7 @@ import { getLanguage, setLanguage } from "./dist/config/Language.js";
 import { getCalendarType } from "./dist/config/CalendarType.js";
 import { getTheme, setTheme } from "./dist/config/Theme.js";
 import { getDefaultFontLoading } from "./dist/config/Fonts.js";
+import { getEnableDefaultTooltips } from "./dist/config/Tooltips.js";
 import { getThemeRoot, setThemeRoot } from "./dist/config/ThemeRoot.js";
 import { getNoConflict, setNoConflict } from "./dist/config/NoConflict.js";
 import { getFirstDayOfWeek, getLegacyDateCalendarCustomizing } from "./dist/config/FormatSettings.js";
@@ -55,6 +56,7 @@ window["sap-ui-webcomponents-bundle"] = {
 		getFirstDayOfWeek,
 		getLegacyDateCalendarCustomizing,
 		getDefaultFontLoading,
+		getEnableDefaultTooltips,
 	},
 	getCurrentRuntimeIndex,
 	getIconNames,

diff --git a/packages/base/src/InitialConfiguration.ts b/packages/base/src/InitialConfiguration.ts
@@ -22,6 +22,7 @@ type InitialConfig = {
 	formatSettings: FormatSettings,
 	fetchDefaultLanguage: boolean,
 	defaultFontLoading: boolean,
+	enableDefaultTooltips: boolean,
 };
 
 let initialConfig: InitialConfig = {
@@ -37,6 +38,7 @@ let initialConfig: InitialConfig = {
 	formatSettings: {},
 	fetchDefaultLanguage: false,
 	defaultFontLoading: true,
+	enableDefaultTooltips: true,
 };
 
 /* General settings */
@@ -80,6 +82,11 @@ const getDefaultFontLoading = () => {
 	return initialConfig.defaultFontLoading;
 };
 
+const getEnableDefaultTooltips = () => {
+	initConfiguration();
+	return initialConfig.enableDefaultTooltips;
+};
+
 /**
  * Get the configured calendar type
  * @returns { String } the name of the configured calendar type
@@ -225,4 +232,5 @@ export {
 	getTimezone,
 	getFormatSettings,
 	getDefaultFontLoading,
+	getEnableDefaultTooltips,
 };
diff --git a/packages/base/src/config/Tooltips.ts b/packages/base/src/config/Tooltips.ts
@@ -0,0 +1,36 @@
+import { getEnableDefaultTooltips as getConfiguredEnableDefaultTooltips } from "../InitialConfiguration.js";
+
+let _enableDefaultTooltips: boolean;
+
+/**
+ * Returns if the "enableDefaultTooltips" configuration is set.
+ * @public
+ * @since 2.1.0
+ * @returns { boolean }
+ */
+const getEnableDefaultTooltips = (): boolean => {
+	if (_enableDefaultTooltips === undefined) {
+		_enableDefaultTooltips = getConfiguredEnableDefaultTooltips();
+	}
+
+	return _enableDefaultTooltips;
+};
+
+/**
+ * Defines the "enableDefaultTooltips" setting.
+ *
+ * - When set to "true" (default), the components will display default tooltips.
+ * - When set to "false", the components will NOT display default tooltips.
+ *
+ * @public
+ * @since 2.1.0
+ * @param { boolean } enableDefaultTooltips
+ */
+const setEnableDefaultTooltips = (enableDefaultTooltips: boolean) => {
+	_enableDefaultTooltips = enableDefaultTooltips;
+};
+
+export {
+	getEnableDefaultTooltips,
+	setEnableDefaultTooltips,
+};
diff --git a/packages/base/test/pages/ConfigurationScript.html b/packages/base/test/pages/ConfigurationScript.html
@@ -35,7 +35,8 @@
             "noConflict": {
                 "events": ["selection-change", "header-click"]
             },
-            "defaultFontLoading": false
+            "defaultFontLoading": false,
+            "enableDefaultTooltips": false
         }
     </script>
 

diff --git a/packages/base/test/specs/ConfigurationScript.spec.js b/packages/base/test/specs/ConfigurationScript.spec.js
@@ -85,4 +85,12 @@ describe("Configuration script has effect", () => {
 		});
 		assert.strictEqual(res, false, "defaultFontLoading is false");
 	});
+
+	it("Tests that enableDefaultTooltips is applied", async () => {
+		const res = await browser.executeAsync(done => {
+			const config = window['sap-ui-webcomponents-bundle'].configuration;
+			done(config.getEnableDefaultTooltips());
+		});
+		assert.strictEqual(res, false, "enableDefaultTooltips is false");
+	});
 });
diff --git a/packages/main/src/Button.ts b/packages/main/src/Button.ts
@@ -25,6 +25,7 @@ import {
 } from "@ui5/webcomponents-base/dist/Device.js";
 import willShowContent from "@ui5/webcomponents-base/dist/util/willShowContent.js";
 import { submitForm, resetForm } from "@ui5/webcomponents-base/dist/features/InputElementsFormSupport.js";
+import { getEnableDefaultTooltips } from "@ui5/webcomponents-base/dist/config/Tooltips.js";
 import type { IFormElement } from "@ui5/webcomponents-base/dist/features/InputElementsFormSupport.js";
 import ButtonDesign from "./types/ButtonDesign.js";
 import ButtonType from "./types/ButtonType.js";
@@ -359,7 +360,7 @@ class Button extends UI5Element implements IButton, IFormElement {
 		this.hasEndIcon = !!this.endIcon;
 		this.iconOnly = this.isIconOnly;
 
-		this.buttonTitle = this.tooltip || await getIconAccessibleName(this.icon);
+		this.buttonTitle = this.tooltip || await this.getDefaultTooltip();
 	}
 
 	_onclick(e: MouseEvent) {
@@ -501,6 +502,14 @@ class Button extends UI5Element implements IButton, IFormElement {
 		};
 	}
 
+	getDefaultTooltip() {
+		if (!getEnableDefaultTooltips()) {
+			return;
+		}
+
+		return getIconAccessibleName(this.icon);
+	}
+
 	get buttonTypeText() {
 		return Button.i18nBundle.getText(Button.typeTextMappings()[this.design]);
 	}
@@ -524,7 +533,7 @@ class Button extends UI5Element implements IButton, IFormElement {
 	}
 
 	get showIconTooltip() {
-		return this.iconOnly && !this.tooltip;
+		return getEnableDefaultTooltips() && this.iconOnly && !this.tooltip;
 	}
 
 	get ariaLabelText() {

diff --git a/packages/main/src/RatingIndicator.ts b/packages/main/src/RatingIndicator.ts
@@ -1,7 +1,7 @@
 import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
 import event from "@ui5/webcomponents-base/dist/decorators/event.js";
 import property from "@ui5/webcomponents-base/dist/decorators/property.js";
-
+import { getEnableDefaultTooltips } from "@ui5/webcomponents-base/dist/config/Tooltips.js";
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
 import {
@@ -295,8 +295,11 @@ class RatingIndicator extends UI5Element {
 		return this.disabled ? "-1" : tabindex || "0";
 	}
 
-	get ratingTooltip() {
-		return this.tooltip || this.defaultTooltip;
+	get ratingTooltip(): string | undefined {
+		if (this.tooltip) {
+			return this.tooltip;
+		}
+		return getEnableDefaultTooltips() ? this.defaultTooltip : undefined;
 	}
 
 	get defaultTooltip() {

diff --git a/packages/main/src/SegmentedButtonItem.ts b/packages/main/src/SegmentedButtonItem.ts
@@ -3,6 +3,7 @@ import property from "@ui5/webcomponents-base/dist/decorators/property.js";
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import type I18nBundle from "@ui5/webcomponents-base/dist/i18nBundle.js";
 import { getI18nBundle } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+import { getEnableDefaultTooltips } from "@ui5/webcomponents-base/dist/config/Tooltips.js";
 import { isDesktop } from "@ui5/webcomponents-base/dist/Device.js";
 import { isSpaceShift } from "@ui5/webcomponents-base/dist/Keys.js";
 import { getEffectiveAriaLabelText } from "@ui5/webcomponents-base/dist/util/AriaLabelHelper.js";
@@ -206,7 +207,7 @@ class SegmentedButtonItem extends UI5Element implements IButton, ISegmentedButto
 	}
 
 	get showIconTooltip() {
-		return this.iconOnly && !this.tooltip;
+		return getEnableDefaultTooltips() && this.iconOnly && !this.tooltip;
 	}
 
 	static async onDefine() {

diff --git a/packages/main/test/pages/base/Tooltips.html b/packages/main/test/pages/base/Tooltips.html
@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+	<meta charset="utf-8">
+	<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+	<title>Tooltips</title>
+	<script src="../%VITE_BUNDLE_PATH%" type="module"></script>
+</head>
+
+<body class="card1auto">
+	<ui5-icon name="settings"></ui5-icon>
+	<ui5-icon name="settings" show-tooltip></ui5-icon>
+	<ui5-button id="btn" icon="settings"></ui5-button>
+	<ui5-rating-indicator id="rt" icon="settings"></ui5-rating-indicator>
+	<ui5-toggle-button icon="settings"></ui5-toggle-button>
+	<ui5-segmented-button id="segBtn">
+		<ui5-segmented-button-item id="segBtnItem" icon="add"></ui5-segmented-button-item>
+		<ui5-segmented-button-item id="segBtnItem2" icon="settings"></ui5-segmented-button-item>
+		<ui5-segmented-button-item id="segBtnItem3" icon="activate"></ui5-segmented-button-item>
+	</ui5-segmented-button>
+</body>
diff --git a/packages/main/test/specs/base/Tooltips.spec.js b/packages/main/test/specs/base/Tooltips.spec.js
@@ -0,0 +1,27 @@
+import { assert } from "chai";
+
+describe("Default Tooltips", () => {
+	before(async () => {
+		await browser.url(`test/pages/base/Tooltips.html?sap-ui-enableDefaultTooltips=false`);
+	});
+
+	it("Tooltips turned off", async () => {
+		const btn = await browser.$("#btn").shadow$(".ui5-button-root");
+		const btnIcon = await browser.$("#btn").shadow$(".ui5-button-icon");
+		const rt = await browser.$("#rt").shadow$(".ui5-rating-indicator-root");
+		const segBtnItem = await browser.$("#segBtnItem").shadow$(".ui5-segmented-button-item-root");
+		const segBtnItemIcon = await browser.$("#segBtnItem").shadow$(".ui5-segmented-button-item-icon");
+
+		const btnTitle = await btn.getAttribute("title");
+		const btnIconTitle = await btnIcon.getAttribute("title");
+		const rtTitle = await rt.getAttribute("title");
+		const segBtnItemTitle = await segBtnItem.getAttribute("title");
+		const segBtnItemIconTitle = await segBtnItemIcon.getAttribute("title");
+
+		assert.notOk(btnTitle, "An icon only Button has no default tooltip.");
+		assert.notOk(btnIconTitle, "An icon only Button icon has no default tooltip.");
+		assert.notOk(rtTitle, "The Rating Indicator has no default tooltip.");
+		assert.notOk(segBtnItemTitle, "An icon only Segmented Button Item has no default tooltip");
+		assert.notOk(segBtnItemIconTitle, "An icon only Segmented Button Item icon has no default tooltip");
+	});
+});