feat(framework): Add dynamic language change and on-demand rerendering (#1746)

Author: vladitasev

docs/Configuration.md

@@ -34,7 +34,18 @@ The `theme` setting values above are the technical names of our themes.
 
 In order to have RTL mode, just set the HTML attribute `dir` to `rtl` on the `body`, `html` or any other relevant region of your application.
 
-This configuration setting should not be used by applications. It is only internally used for specific integration scenarios.
+The `RTL` configuration setting should not be used by applications. It is only internally used for specific integration scenarios.
+
+*Note:* Whenever you change `dir` dynamically, make sure you call the `applyDirection` method to re-render the RTL-aware components.
+
+Example:
+```js
+import applyDirection from "@ui5/webcomponents-base/dist/locale/applyDirection.js";
+
+document.body.dir = "rtl";
+applyDirection();
+```
+
 
 <a name="animationMode"></a>
 ### Animation Mode
@@ -122,7 +133,7 @@ To do so, please import the desired functionality from the respective `"@ui5/web
 import { getTheme, setTheme } from "@ui5/webcomponents-base/dist/config/Theme.js";
 import { getNoConflict, setNoConflict } from "@ui5/webcomponents-base/dist/config/NoConflict.js";
 import { getAnimationMode } from "@ui5/webcomponents-base/dist/config/AnimationMode.js";
-import { getLanguage } from "@ui5/webcomponents-base/dist/config/Language.js";
+import { getLanguage, setLanguage } from "@ui5/webcomponents-base/dist/config/Language.js";
 import { getCalendarType } from "@ui5/webcomponents-base/dist/config/CalendarType.js";
 import { getFirstDayOfWeek } from "@ui5/webcomponents-base/dist/config/FormatSettings.js";
 ```

packages/base/src/CustomElementsRegistry.js

@@ -1,3 +1,5 @@
+import setToArray from "./util/setToArray.js";
+
 const Definitions = new Set();
 const Failures = new Set();
 let failureTimeout;
@@ -11,11 +13,7 @@ const isTagRegistered = tag => {
 };
 
 const getAllRegisteredTags = () => {
-	const arr = [];
-	Definitions.forEach(tag => {
-		arr.push(tag);
-	});
-	return arr;
+	return setToArray(Definitions);
 };
 
 const recordTagRegistrationFailure = tag => {
@@ -29,11 +27,7 @@ const recordTagRegistrationFailure = tag => {
 };
 
 const displayFailedRegistrations = () => {
-	const tags = []; // IE only supports Set.prototype.forEach
-	Failures.forEach(tag => {
-		tags.push(tag);
-	});
-	console.warn(`The following tags have already been defined by a different UI5 Web Components version: ${tags.join(", ")}`); // eslint-disable-line
+	console.warn(`The following tags have already been defined by a different UI5 Web Components version: ${setToArray(Failures).join(", ")}`); // eslint-disable-line
 	Failures.clear();
 };
 

packages/base/src/EventProvider.js

@@ -34,16 +34,24 @@ class EventProvider {
 		}
 	}
 
+	/**
+	 * Fires an event and returns the results of all event listeners as an array.
+	 * Example: If listeners return promises, you can: await fireEvent("myEvent") to know when all listeners have finished.
+	 *
+	 * @param eventName the event to fire
+	 * @param data optional data to pass to each event listener
+	 * @returns {Array} an array with the results of all event listeners
+	 */
 	fireEvent(eventName, data) {
 		const eventRegistry = this._eventRegistry;
 		const eventListeners = eventRegistry[eventName];
 
 		if (!eventListeners) {
-			return;
+			return [];
 		}
 
-		eventListeners.forEach(event => {
-			event["function"].call(this, data); // eslint-disable-line
+		return eventListeners.map(event => {
+			return event["function"].call(this, data); // eslint-disable-line
 		});
 	}
 

packages/base/src/RenderScheduler.js

@@ -1,7 +1,9 @@
 import RenderQueue from "./RenderQueue.js";
 import { getAllRegisteredTags } from "./CustomElementsRegistry.js";
+import { isRtlAware } from "./locale/RTLAwareRegistry.js";
 
 const MAX_RERENDER_COUNT = 10;
+const registeredElements = new Set();
 
 // Tells whether a render task is currently scheduled
 let renderTaskId;
@@ -141,6 +143,36 @@ class RenderScheduler {
 			renderTaskPromise = undefined;
 		}
 	}
+
+	static register(element) {
+		registeredElements.add(element);
+	}
+
+	static deregister(element) {
+		registeredElements.delete(element);
+	}
+
+	/**
+	 * Re-renders all UI5 Elements on the page, with the option to specify filters to rerender only some components.
+	 *
+	 * Usage:
+	 * reRenderAllUI5Elements() -> rerenders all components
+	 * reRenderAllUI5Elements({rtlAware: true}) -> re-renders only rtlAware components
+	 * reRenderAllUI5Elements({languageAware: true}) -> re-renders only languageAware components
+	 * reRenderAllUI5Elements({rtlAware: true, languageAware: true}) -> re-renders components that are rtlAware or languageAware
+	 *
+	 * @public
+	 * @param {Object|undefined} filters - Object with keys that can be "rtlAware" or "languageAware"
+	 */
+	static reRenderAllUI5Elements(filters) {
+		registeredElements.forEach(element => {
+			const rtlAware = isRtlAware(element.constructor);
+			const languageAware = element.constructor.getMetadata().isLanguageAware();
+			if (!filters || (filters.rtlAware && rtlAware) || (filters.languageAware && languageAware)) {
+				RenderScheduler.renderDeferred(element);
+			}
+		});
+	}
 }
 
 export default RenderScheduler;

packages/base/src/UI5Element.js

@@ -15,6 +15,7 @@ import Float from "./types/Float.js";
 import { kebabToCamelCase, camelToKebabCase } from "./util/StringHelper.js";
 import isValidPropertyName from "./util/isValidPropertyName.js";
 import isSlot from "./util/isSlot.js";
+import { markAsRtlAware } from "./locale/RTLAwareRegistry.js";
 
 const metadata = {
 	events: {
@@ -114,6 +115,7 @@ class UI5Element extends HTMLElement {
 				await Promise.resolve();
 			}
 
+			RenderScheduler.register(this);
 			await RenderScheduler.renderImmediately(this);
 			this._domRefReadyPromise._deferredResolve();
 			if (typeof this.onEnterDOM === "function") {
@@ -136,6 +138,7 @@ class UI5Element extends HTMLElement {
 				this._stopObservingDOMChildren();
 			}
 
+			RenderScheduler.deregister(this);
 			if (typeof this.onExitDOM === "function") {
 				this.onExitDOM();
 			}
@@ -672,6 +675,8 @@ class UI5Element extends HTMLElement {
 	 * @returns {String|undefined}
 	 */
 	get effectiveDir() {
+		markAsRtlAware(this.constructor); // if a UI5 Element calls this method, it's considered to be rtl-aware
+
 		const doc = window.document;
 		const dirValues = ["ltr", "rtl"]; // exclude "auto" and "" from all calculations
 		const locallyAppliedDir = getComputedStyle(this).getPropertyValue(GLOBAL_DIR_CSS_VAR);

packages/base/src/UI5ElementMetadata.js

@@ -126,6 +126,14 @@ class UI5ElementMetadata {
 	getEvents() {
 		return this.metadata.events || {};
 	}
+
+	/**
+	 * Determines whether this UI5 Element has any translatable texts (needs to be invalidated upon language change)
+	 * @returns {boolean}
+	 */
+	isLanguageAware() {
+		return !!this.metadata.languageAware;
+	}
 }
 
 const validateSingleProperty = (value, propData) => {

packages/base/src/asset-registries/i18n.js

@@ -1,5 +1,6 @@
 import { getFeature } from "../FeaturesRegistry.js";
 import getLocale from "../locale/getLocale.js";
+import { attachLanguageChange } from "../locale/languageChange.js";
 import { fetchTextOnce } from "../util/FetchHelper.js";
 import normalizeLocale from "../locale/normalizeLocale.js";
 import nextFallbackLocale from "../locale/nextFallbackLocale.js";
@@ -63,6 +64,7 @@ const fetchI18nBundle = async packageName => {
 	}
 
 	if (!bundlesForPackage[localeId]) {
+		setI18nBundleData(packageName, null); // reset for the default language (if data was set for a previous language)
 		return;
 	}
 
@@ -90,6 +92,12 @@ const fetchI18nBundle = async packageName => {
 	setI18nBundleData(packageName, data);
 };
 
+// When the language changes dynamically (the user calls setLanguage), re-fetch all previously fetched bundles
+attachLanguageChange(() => {
+	const allPackages = [...bundleData.keys()];
+	return Promise.all(allPackages.map(fetchI18nBundle));
+});
+
 export {
 	fetchI18nBundle,
 	registerI18nBundle,

packages/base/src/config/Language.js

@@ -1,12 +1,41 @@
 import { getLanguage as getConfiguredLanguage } from "../InitialConfiguration.js";
+import { fireLanguageChange } from "../locale/languageChange.js";
+import RenderScheduler from "../RenderScheduler.js";
 
 let language;
 
+/**
+ * Returns the currently configured language, or the browser language as a fallback
+ * @returns {String}
+ */
 const getLanguage = () => {
 	if (language === undefined) {
 		language = getConfiguredLanguage();
 	}
 	return language;
 };
 
-export { getLanguage }; // eslint-disable-line
+/**
+ * Changes the current language, re-fetches all message bundles, updates all language-aware components
+ * and returns a promise that resolves when all rendering is done
+ *
+ * @param newLanguage
+ * @returns {Promise<void>}
+ */
+const setLanguage = async newLanguage => {
+	if (language === newLanguage) {
+		return;
+	}
+
+	language = newLanguage;
+
+	const listenersResults = fireLanguageChange(newLanguage);
+	await Promise.all(listenersResults);
+	RenderScheduler.reRenderAllUI5Elements({ languageAware: true });
+	return RenderScheduler.whenFinished();
+};
+
+export {
+	getLanguage,
+	setLanguage,
+};

packages/base/src/locale/RTLAwareRegistry.js

@@ -0,0 +1,14 @@
+const rtlAwareSet = new Set();
+
+const markAsRtlAware = klass => {
+	rtlAwareSet.add(klass);
+};
+
+const isRtlAware = klass => {
+	return rtlAwareSet.has(klass);
+};
+
+export {
+	markAsRtlAware,
+	isRtlAware,
+};

packages/base/src/locale/applyDirection.js

@@ -0,0 +1,15 @@
+import RenderScheduler from "../RenderScheduler.js";
+
+/**
+ * Re-renders all RTL-aware UI5 Elements.
+ * Call this method whenever you change the "dir" property anywhere in your HTML page
+ * Example: document.body.dir = "rtl"; applyDirection();
+ *
+ * @returns {Promise<void>}
+ */
+const applyDirection = () => {
+	RenderScheduler.reRenderAllUI5Elements({ rtlAware: true });
+	return RenderScheduler.whenFinished();
+};
+
+export default applyDirection;