feat(framework): Allow the registration of custom themes (#1109)

docs/Public Module Imports.md

@@ -318,3 +318,26 @@ import { getFirstDayOfWeek } from "@ui5/webcomponents-base/dist/config/FormatSet
 ```
 
 For more details, please check [Configuration](Configuration.md)
+
+### 6. Assets registration
+
+In order to register a **custom theme**:
+
+```js
+import { registerThemeProperties } from "@ui5/webcomponents-base/dist/AssetRegistry.js"
+```
+
+and then call the method above to register CSS Variables for each theme/package pair.
+
+You can pass the parameters directly, as an object, or as a URL:
+1) Pass the CSS Vars as a string directly.
+
+	`registerThemeProperties("my-package", "my_theme", ":root{--var1: red;}");`
+
+2) Pass the CSS Vars as an object directly. The object must have a "_" property, pointing to a string with the CSS Vars.
+
+	`registerThemeProperties("my-package", "my_theme", {"_": ":root{--var1: red;}"});`
+
+3) Pass a URL to a JSON file, containing the CSS Vars in its "_" property. Will be fetched on demand, not upon registration.
+
+	`registerThemeProperties("my-package", "my_theme", "http://url/to/my/theme.json");`

packages/base/bundle.esm.js

@@ -1,3 +1,5 @@
+import { registerThemeProperties } from "./dist/AssetRegistry.js";
+
 import "./dist/features/calendar/Buddhist.js";
 import "./dist/features/calendar/Islamic.js";
 import "./dist/features/calendar/Japanese.js";
@@ -14,7 +16,7 @@ import "./dist/test-resources/elements/Child.js";
 import "./dist/test-resources/elements/DensityAware.js";
 import "./dist/test-resources/elements/GenericExt.js";
 
-// Test themes
+// Test themes - CSS Vars for the sap_fiori_3, sap_fiori_3_dark, sap_belize and sap_belize_hcb themes
 import "./dist/test-resources/assets/Themes.js";
 
 // used in test pages
@@ -23,6 +25,9 @@ window.RenderScheduler = RenderScheduler;
 import { isIE } from "./dist/Device.js";
 window.isIE = isIE; // attached to the window object for testing purposes
 
+// used for tests - to register a custom theme
+window.registerThemeProperties = registerThemeProperties;
+
 // Note: keep in sync with rollup.config value for IIFE
 import { getAnimationMode } from "./dist/config/AnimationMode.js";
 import { getLanguage } from "./dist/config/Language.js";

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

@@ -3,8 +3,26 @@ import { fetchJsonOnce } from "../util/FetchHelper.js";
 const themeURLs = new Map();
 const themeStyles = new Map();
 const registeredPackages = new Set();
-const SUPPORTED_THEMES = ["sap_fiori_3", "sap_fiori_3_dark", "sap_belize", "sap_belize_hcb"];
+const registeredThemes = new Set();
 
+/**
+ * Used to provide CSS Vars for a specific theme for a specific package.
+ * The CSS Vars can be passed directly as a string (containing them), as an object with a "_" property(containing them in the "_" property), or as a URL.
+ * This URL must point to a JSON file, containing a "_" property.
+ *
+ * Example usage:
+ *  1) Pass the CSS Vars as a string directly.
+ *  registerThemeProperties("my-package", "my_theme", ":root{--var1: red;}");
+ *  2) Pass the CSS Vars as an object directly
+ *  registerThemeProperties("my-package", "my_theme", {"_": ":root{--var1: red;}"});
+ *  3) Pass a URL to a JSON file, containing the CSS Vars in its "_" property. Will be fetched on demand, not upon registration.
+ *  registerThemeProperties("my-package", "my_theme", "http://url/to/my/theme.json");
+ *
+ * @public
+ * @param packageName - the NPM package for which CSS Vars are registered
+ * @param themeName - the theme which the CSS Vars implement
+ * @param style - can be one of three options: a string, an object with a "_" property or a URL to a JSON file with a "_" property
+ */
 const registerThemeProperties = (packageName, themeName, style) => {
 	if (style._) {
 		// JSON object like ({"_": ":root"})
@@ -17,6 +35,7 @@ const registerThemeProperties = (packageName, themeName, style) => {
 		themeURLs.set(`${packageName}_${themeName}`, style);
 	}
 	registeredPackages.add(packageName);
+	registeredThemes.add(themeName);
 };
 
 const getThemeProperties = async (packageName, themeName) => {
@@ -25,8 +44,9 @@ const getThemeProperties = async (packageName, themeName) => {
 		return style;
 	}
 
-	if (!SUPPORTED_THEMES.includes(themeName)) {
-		console.warn(`You have requested non-existing theme - falling back to sap_fiori_3. The supported themes are: ${SUPPORTED_THEMES.join(", ")}.`); /* eslint-disable-line */
+	if (!registeredThemes.has(themeName)) {
+		const regThemesStr = [...registeredThemes.values()].join(", ");
+		console.warn(`You have requested a non-registered theme - falling back to sap_fiori_3. Registered themes are: ${regThemesStr}`); /* eslint-disable-line */
 		return themeStyles.get(`${packageName}_sap_fiori_3`);
 	}
 

packages/base/test/elements/Generic.js

@@ -68,6 +68,7 @@ class Generic extends UI5Element {
 		return `:host {
                     display: inline-block;
                     border: 1px solid black;
+                    color: var(--var1);
                 }`;
 	}
 

packages/base/test/specs/CustomTheme.spec.js

@@ -0,0 +1,25 @@
+const assert = require("chai").assert;
+
+describe("Custom themes can be registered", () => {
+	browser.url("http://localhost:9191/test-resources/pages/AllTestElements.html");
+
+	it("Tests that theme parameters are changed on theme change", () => {
+		const newTheme = 'my_custom_theme';
+
+		const res = browser.executeAsync( async (newTheme, done) => {
+			const var1 = "--var1: #555555";
+
+			window.registerThemeProperties("@ui5/webcomponents-base-test", newTheme, `:root{ ${var1}; }`);
+
+			const config = window['sap-ui-webcomponents-bundle'].configuration;
+			await config.setTheme(newTheme);
+
+			const style = document.querySelector(`style[data-ui5-theme-properties="@ui5/webcomponents-base-test"]`);
+			const varsFound = style && style.textContent.includes(var1);
+			return done(varsFound);
+		}, newTheme);
+
+		assert.strictEqual(res, true, "Theme parameters changed");
+	});
+
+});