feat: register custom theme properties

[vladitasev]

The new registerCustomThemeProperties function allows developers to register a theme loader for components packages (f.e. @ui5/webcomponents) that will be executed after the default theme loader that comes with the library.

This allows to set custom values for library-specific CSS variables.

1. How to build

1. Source file custom-css/my_custom_theme.css:

:root {
    --_ui5_button_base_height: 4rem;
    --_ui5_button_base_padding: 2rem;
}

2. Sample package.json file for your project

{
  "scripts": {
    "build": "postcss custom-css/*.css --config postcss.config.cjs"
  },
  "dependencies": {
    "@ui5/webcomponents-tools": "^1.18.0"
  }
}

3. Content of postcss.config.cjs

const postcssCSStoESM = require('@ui5/webcomponents-tools/lib/postcss-css-to-esm/index.js');
const postcssScopeVars = require('@ui5/webcomponents-tools/lib/postcss-scope-vars/index.js');
const toolsPackageJSON = require("@ui5/webcomponents-tools/package.json");

module.exports = {
		plugins: [
			postcssScopeVars({ version: toolsPackageJSON.version }),
			postcssCSStoESM({ includeDefaultTheme: false, packageName: "" }),
		]
}

The result of calling npm run build will be a file called custom-css/my_custom_theme.css.js with the following content:

export default {packageName:"",fileName:"s",content:":root {\n    --_ui5-v1-19-0-rc-1_button_base_height: 4rem;\n    --_ui5-v1-19-0-rc-1_button_base_padding: 2rem;\n}"}

2. How to use (sample index.js file):

import { registerCustomThemePropertiesLoader } from "@ui5/webcomponents-base/dist/AssetRegistry.js";
const customThemeLoader = async theme => {
	if (theme === "my_custom_theme") {
		return (await import("./custom-css/my_custom_theme.css.js")).default;
	}
}
registerCustomThemePropertiesLoader("@ui5/webcomponents", "my_custom_theme", customThemeLoader);

3. Build utility

An overrides directory in src/themes indicates a trigger that the files that follow are overrides for some other packages, and their version should be used to scope CSS Vars, not the version of the current package that is being built.