theme-loader-api 1.0.0

package/README.md

@@ -0,0 +1,210 @@
+## Summary
+
+The Web theme loader API exposes 3 contracts:
+1. `static init()` of themeLoader to be called during app startup.
+2. `static loadTheme(picked: string | null, appColorsDir?: string | null)` to be called when the app user picks one from available themes.
+3. `static get selectedTheme(): string | null` of themeLoader to give the URL of the selected theme, so GUI may display which theme is in-use.
+
+Because the theme should be loaded at startup before the Web app rendering, the respective config must be loaded synchronously ASAP.
+
+The GUI of theme selection is independent of the Web theme loader API. For example, in addition to Select and Menu for multiple themes, you may use Switch for switching between light and dark. 
+
+Remarks:
+* Modern browsers like Chrome, Edge, Safari, and Firefox support a built-in concept of light/dark preference. Depending on your UX design, if you would not provide UI component for changing theme, then CSS only solution works well:
+```css
+<link rel="stylesheet" href="my-light.css" media="(prefers-color-scheme: light)">
+<link rel="stylesheet" href="my-dark.css" media="(prefers-color-scheme: dark)">
+```
+
+## Installation
+1. Install [theme-loader-api](https://www.npmjs.com/package/theme-loader-api).
+
+## Integration
+1. Call `ThemeLoader.loadTheme()` before the [bootstrap of the Web app](https://github.com/zijianhuang/nmce/blob/master/projects/demoapp/src/main.ts).
+1. In the [UI component presenting the theme picker](https://github.com/zijianhuang/nmce/blob/master/projects/demoapp/src/app/app.component.ts), convert the themes dictionary to an array which will be used to present the list. And call `ThemeLoader.loadTheme()` when the picker picks a theme.
+1. Prepare [`siteconfig.js`](https://github.com/zijianhuang/nmce/blob/master/projects/demoapp/src/conf/siteconfig.js) and add `<script src="conf/siteconfig.js"></script>` to [index.html](https://github.com/zijianhuang/nmce/blob/master/projects/demoapp/src/index.html) if you want flexibility after build and deployment. Or, simply provide constant THEME_CONFIG in app code.
+
+### [Angular Example](https://github.com/zijianhuang/DemoCoreWeb/blob/master/AngularHeroes/)
+
+ [main.ts](https://github.com/zijianhuang/DemoCoreWeb/blob/master/AngularHeroes/src/main.ts)
+ ```ts
+ThemeLoader.init();
+bootstrapApplication(AppComponent, appConfig); 
+```
+
+[theme-select.component.ts](https://github.com/zijianhuang/DemoCoreWeb/blob/master/AngularHeroes/src/app/theme-select.component.ts)
+```ts
+	constructor() {
+		this.themes = AppConfigConstants.themesDic ? Object.keys(AppConfigConstants.themesDic).map(k => {
+			const c = AppConfigConstants.themesDic![k];
+			const obj: ThemeDef = {
+				display: c.display,
+				filePath: k,
+				dark: c.dark
+			};
+			return obj;
+		}) : undefined;
+	}
+
+	themeSelectionChang(e: MatSelectChange) {
+		ThemeLoader.loadTheme(e.value);
+	}
+```
+
+[theme-select.component.html](https://github.com/zijianhuang/DemoCoreWeb/blob/master/AngularHeroes/src/app/theme-select.component.html)
+```html
+<mat-select #themeSelect (selectionChange)="themeSelectionChang($event)" [value]="currentTheme">
+	@for (item of themes; track $index) {
+	<mat-option [value]="item.filePath">{{item.display}}</mat-option>
+	}
+</mat-select>
+```
+
+[siteconfig.js](https://github.com/zijianhuang/DemoCoreWeb/blob/master/docs/angular/conf/siteconfig.js)
+```js
+const THEME_CONFIG = {
+	apiBaseUri: 'https://mybackend.com/',
+	themesDic: {
+		"assets/themes/azure-blue.css": { display: "Azure & Blue", dark: false },
+		"assets/themes/rose-red.css": { display: "Roes & Red", dark: false },
+		"assets/themes/magenta-violet.css": { display: "Magenta & Violet", dark: true },
+		"assets/themes/cyan-orange.css": { display: "Cyan & Orange", dark: true }
+	},
+	themeLoaderSettings: {
+		storageKey: 'app.theme',
+		themeLinkId: 'theme',
+		appColorsDir: 'conf/',
+		appColorsLinkId: 'app-colors',
+		colorsCss: 'colors.css',
+		colorsDarkCss: 'colors-dark.css'
+	}
+}
+```
+
+[index.html](https://github.com/zijianhuang/DemoCoreWeb/blob/master/AngularHeroes/src/index.html)
+```html
+    <script src="conf/siteconfig.js"></script>
+</head>
+```
+
+### React Example
+
+[index.tsx](https://github.com/zijianhuang/DemoCoreWeb/blob/master/ReactHeroes/src/index.tsx)
+```ts
+ThemeLoader.init();
+
+const root = ReactDOM.createRoot(
+  document.getElementById('root') as HTMLElement
+);
+root.render(...
+```
+
+[Home.tsx](https://github.com/zijianhuang/DemoCoreWeb/blob/master/ReactHeroes/src/Home.tsx)
+```ts
+	const themes = AppConfigConstants.themesDic ? Object.keys(AppConfigConstants.themesDic).map(k => {
+		const c = AppConfigConstants.themesDic![k];
+		const obj: ThemeDef = {
+			display: c.display,
+			filePath: k,
+			dark: c.dark
+		};
+		return obj;
+	}) : undefined;
+
+	const [currentTheme, setCurrentTheme] = useState(() => ThemeLoader.selectedTheme ?? undefined);
+	const handleChange = (event: React.ChangeEvent<HTMLSelectElement>) => {
+		const v = event.target.value;
+		setCurrentTheme(v);
+		ThemeLoader.loadTheme(v);
+	};
+
+	return (
+		<>
+			<h1>React Heroes!</h1>
+			<div>
+				<label htmlFor="theme-select">Themes </label>
+				<select
+					id="theme-select"
+					value={currentTheme ?? ""}
+					onChange={handleChange}
+				>
+					{themes?.map((item) => (
+						<option key={item.filePath} value={item.filePath}>
+							{item.display}
+						</option>
+					))}
+				</select>
+			</div>
+```
+
+[siteconfig.js](https://github.com/zijianhuang/DemoCoreWeb/blob/master/docs/react/conf/siteconfig.js)
+```js
+const THEME_CONFIG = {
+	apiBaseUri: 'https://mybackend.com/',
+	themesDic: {
+		"assets/themes/azure-blue.css": { display: "Azure & Blue", dark: false },
+		"assets/themes/rose-red.css": { display: "Roes & Red", dark: false },
+		"assets/themes/magenta-violet.css": { display: "Magenta & Violet", dark: true },
+		"assets/themes/cyan-orange.css": { display: "Cyan & Orange", dark: true }
+	},
+	themeLoaderSettings: {
+		storageKey: 'app.theme',
+		themeLinkId: 'theme',
+		appColorsDir: 'conf/',
+		appColorsLinkId: 'app-colors',
+		colorsCss: 'colors.css',
+		colorsDarkCss: 'colors-dark.css'
+	}
+}
+```
+
+[index.html](https://github.com/zijianhuang/DemoCoreWeb/blob/master/ReactHeroes/public/index.html)
+```html
+    <script src="conf/siteconfig.js"></script>
+</head>
+```
+
+### Respect prefers-color-scheme
+
+By default, this API will pick the first available theme in the dictionary during the first startup of the Web app, and use the last pick afterward. If you want to respect prefers-color-scheme during the initial load of the Web app, you may use the following in the app's bootstrap:
+```ts
+const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+var r = findFirstTheme(isDark);
+if (r) {
+	ThemeLoader.loadTheme(r.filePath);
+}
+
+platformBrowser().bootstrapModule(AppModule, { applicationProviders: [provideZoneChangeDetection()], })
+	.catch(err => console.error(err));
+
+function findFirstTheme(dark: boolean): { filePath: string; theme: ThemeValue } | undefined {
+	const entry = Object.entries(AppConfigConstants.themesDic!).find(
+		([, theme]) => theme.dark === dark
+	);
+
+	return entry
+		? { filePath: entry[0], theme: entry[1] }
+		: undefined;
+}
+
+```
+
+## How About I18N and L10N?
+
+The only things need to be translated is the display name of each theme.
+
+### Solution 1: No need for I18N and Use Icon To Represent Theme Impression
+
+You may extend `interface ThemeDef`, and make it contain some meta info of generating SVG icons presenting respective theme. And the icons will be inline with the HTML template. [Angular Material Components site](https://material.angular.dev/) uses [this approach](https://github.com/angular/components/blob/main/docs/src/app/shared/theme-picker/).
+
+Or you may just hand-draw some SVG icons and linked it in the HTML template.
+
+### Solution 2: Create Dictionary in App Code
+
+Depending the framework like Angular or the library like React, there could be a few ways to create a dictionary to lookup translations and create translations.
+
+### Solution 3: Post Build Processing
+
+If you are using `siteconfig.js`, the JS file should not be included in the hash tables of the service worker for automatic update. 
+
+In Angular, each locale has its own build, therefore, you may craft some post build script to inject the translated names into the `siteconfig.js` of each build.

package/fesm2022/theme-loader-api.mjs

@@ -0,0 +1,110 @@
+const ThemeConfigConstants = {
+    ...(typeof THEME_CONFIG === 'undefined' ? {} : THEME_CONFIG),
+};
+
+/**
+ * Helper class to load default theme or selected theme among themes defined in app startup settings.
+ * index.html should not have the theme css link during design time.
+ * In addition to the main theme which could be one the prebuilt themes reusable across apps, like one of those of Angular Material,
+ * the app may optionally has its own app css file for colors.
+ */
+class ThemeLoader {
+    static settings = ThemeConfigConstants.themeLoaderSettings;
+    /**
+     * selected theme file name saved in localStorage.
+     */
+    static get selectedTheme() {
+        return this.settings ? localStorage.getItem(this.settings.storageKey) : null;
+    }
+    ;
+    static set selectedTheme(v) {
+        if (this.settings) {
+            localStorage.setItem(this.settings.storageKey, v);
+        }
+    }
+    ;
+    /**
+     * Load default or previously selected theme during app startup, typically used before calling `bootstrapApplication()`.
+     */
+    static init() {
+        this.loadTheme(this.selectedTheme);
+    }
+    /**
+     * Load theme during operation through `ThemeLoader.loadTheme(themeDicKey);`.
+     * @param picked one of the prebuilt themes, typically used with the app's theme picker.
+     */
+    static loadTheme(picked) {
+        if (!ThemeConfigConstants.themesDic || !this.settings || Object.keys(ThemeConfigConstants.themesDic).length === 0) {
+            console.error('AppConfigConstants need to have themesDic with at least 1 item, and themeKeys.');
+            return;
+        }
+        let themeLink = document.getElementById(this.settings.themeLinkId);
+        if (themeLink) { // app has been loaded in the browser page/tab.
+            const currentTheme = themeLink.href.substring(themeLink.href.lastIndexOf('/') + 1);
+            const notToLoad = picked == currentTheme;
+            if (notToLoad) {
+                return;
+            }
+            const themeValue = ThemeConfigConstants.themesDic[picked];
+            if (!themeValue) {
+                return;
+            }
+            themeLink.href = picked;
+            this.selectedTheme = picked;
+            console.info(`theme altered to ${picked}.`);
+            if (this.settings.appColorsLinkId) {
+                let appColorsLink = document.getElementById(this.settings.appColorsLinkId);
+                if (appColorsLink) {
+                    if (themeValue.dark != null && this.settings.colorsDarkCss && this.settings.colorsCss) {
+                        const customFile = themeValue.dark ? this.settings.colorsDarkCss : this.settings.colorsCss;
+                        appColorsLink.href = (this.settings.appColorsDir ?? '') + customFile;
+                    }
+                    else if (this.settings.colorsCss) {
+                        appColorsLink.href = (this.settings.appColorsDir ?? '') + this.settings.colorsCss;
+                    }
+                }
+            }
+        }
+        else { // when app is loaded for the first time, then create 
+            themeLink = document.createElement('link');
+            themeLink.id = this.settings.themeLinkId;
+            themeLink.rel = 'stylesheet';
+            const themeDicKey = picked ?? Object.keys(ThemeConfigConstants.themesDic)[0];
+            themeLink.href = themeDicKey;
+            document.head.appendChild(themeLink);
+            this.selectedTheme = themeDicKey;
+            console.info(`Initially loaded theme ${themeDicKey}`);
+            if (this.settings.appColorsLinkId) {
+                const appColorsLink = document.createElement('link');
+                appColorsLink.id = this.settings.appColorsLinkId;
+                appColorsLink.rel = 'stylesheet';
+                const themeValue = ThemeConfigConstants.themesDic[themeDicKey];
+                if (themeValue.dark != null && this.settings.colorsDarkCss && this.settings.colorsCss) {
+                    const customFile = themeValue.dark ? this.settings.colorsDarkCss : this.settings.colorsCss;
+                    appColorsLink.href = (this.settings.appColorsDir ?? '') + customFile;
+                }
+                else if (this.settings.colorsCss) {
+                    appColorsLink.href = (this.settings.appColorsDir ?? '') + this.settings.colorsCss;
+                }
+                if (appColorsLink.href) {
+                    document.head.appendChild(appColorsLink);
+                    console.info(`appColors ${appColorsLink} loaded.`);
+                }
+                else {
+                    console.warn(`With appColorsLinkId defined, dark&colorsCss&colorDarkCss or colorsCss should be defined.`);
+                }
+            }
+        }
+    }
+}
+
+/*
+ * Public API Surface of theme-loader-api
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { ThemeConfigConstants, ThemeLoader };
+//# sourceMappingURL=theme-loader-api.mjs.map

package/fesm2022/theme-loader-api.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme-loader-api.mjs","sources":["../../../projects/theme-loader-api/src/lib/themeDef.ts","../../../projects/theme-loader-api/src/lib/themeLoader.ts","../../../projects/theme-loader-api/src/public-api.ts","../../../projects/theme-loader-api/src/theme-loader-api.ts"],"sourcesContent":["export interface ThemeValue {\r\n\t/** Display name used in the UI like menu or dropdown */\r\n\tdisplay: string;\r\n\r\n\t/** Dark them or not. Optionally to tell which optional app level colors CSS to use, if some app level colors need to adapt the light or dark theme. */\r\n\tdark?: boolean;\r\n}\r\n\r\nexport interface ThemeDef extends ThemeValue {\r\n\t/** Relative path or URL to CDN */\r\n\tfilePath: string;\r\n}\r\n\r\nexport interface ThemesDic {\r\n\t[filePath: string]: ThemeValue\r\n}\r\n\r\nexport interface ThemeLoaderSettings {\r\n\t/**\r\n\t * The key of themeDic to store the selected theme in local storage of browser. Each app or site must have a unique key to avoid conflict with other apps or sites.\r\n\t */\r\n\tstorageKey: string;\r\n\r\n\t/**\r\n\t * The id of the link element in index.html for loading the theme CSS file dynamically during app startup and operation.\r\n\t */\r\n\tthemeLinkId: string;\r\n\r\n\t/** \r\n\t * Optionally the app may has an app level colors CSS declaring colors neutral to the light or dark theme, in addition to a prebuilt theme reused across apps. \r\n\t * If some colors need to adapt the light or dark theme, having those colors defined in colorsCss and colorsDarkCss is convenient for SDLC, since you can\r\n\t * use tools to flip colors to dark or light.\r\n\t */\r\n\tappColorsLinkId?: string;\r\n\r\n\t/**\r\n\t * If undefined or null, app colors css is in root.\r\n\t * Effected only when appColorsLinkId is defined.\r\n\t */\r\n\tappColorsDir?: string;\r\n\r\n\t/** \r\n\t * Optionally the app may has an app level colors CSS declaring colors adapting to the light theme. \r\n\t * If the app uses only light or dark theme, for example ThemeValue.dark is not defined, this alone is enough, not needing colorsDarkCss. \r\n\t*/\r\n\tcolorsCss?: string;\r\n\r\n\t/** \r\n\t * Optionally the app may has an app level colors CSS declaring colors adapting to the dark theme. \r\n\t * If the app uses only light or dark theme, there's no need to declare this. \r\n\t */\r\n\tcolorsDarkCss?: string;\r\n}\r\n\r\ninterface Theme_Config {\r\n\tthemesDic?: ThemesDic,\r\n\r\n\tthemeLoaderSettings?: ThemeLoaderSettings\r\n}\r\n\r\ndeclare const THEME_CONFIG: Theme_Config\r\n\r\nexport const ThemeConfigConstants: Theme_Config = {\r\n\t...(typeof THEME_CONFIG === 'undefined' ? {} : THEME_CONFIG),\r\n}\r\n","import { ThemeConfigConstants } from \"./themeDef\"; //just for typed\r\n\r\n/**\r\n * Helper class to load default theme or selected theme among themes defined in app startup settings.\r\n * index.html should not have the theme css link during design time.\r\n * In addition to the main theme which could be one the prebuilt themes reusable across apps, like one of those of Angular Material, \r\n * the app may optionally has its own app css file for colors.\r\n */\r\nexport class ThemeLoader {\r\n\tprivate static readonly settings = ThemeConfigConstants.themeLoaderSettings;\r\n\r\n\t/**\r\n\t * selected theme file name saved in localStorage.\r\n\t */\r\n\tstatic get selectedTheme(): string | null {\r\n\t\treturn this.settings ? localStorage.getItem(this.settings.storageKey) : null;\r\n\t};\r\n\tprivate static set selectedTheme(v: string) {\r\n\t\tif (this.settings) {\r\n\t\t\tlocalStorage.setItem(this.settings.storageKey, v);\r\n\t\t}\r\n\t};\r\n\r\n\t/**\r\n\t * Load default or previously selected theme during app startup, typically used before calling `bootstrapApplication()`.\r\n\t */\r\n\tstatic init(){\r\n\t\tthis.loadTheme(this.selectedTheme);\r\n\t}\r\n\r\n\t/**\r\n\t * Load theme during operation through `ThemeLoader.loadTheme(themeDicKey);`.\r\n\t * @param picked one of the prebuilt themes, typically used with the app's theme picker.\r\n\t */\r\n\tstatic loadTheme(picked: string | null) {\r\n\t\tif (!ThemeConfigConstants.themesDic || !this.settings || Object.keys(ThemeConfigConstants.themesDic).length === 0) {\r\n\t\t\tconsole.error('AppConfigConstants need to have themesDic with at least 1 item, and themeKeys.');\r\n\t\t\treturn;\r\n\t\t}\r\n\r\n\t\tlet themeLink = document.getElementById(this.settings.themeLinkId) as HTMLLinkElement;\r\n\t\tif (themeLink) { // app has been loaded in the browser page/tab.\r\n\t\t\tconst currentTheme = themeLink.href.substring(themeLink.href.lastIndexOf('/') + 1);\r\n\t\t\tconst notToLoad = picked == currentTheme;\r\n\t\t\tif (notToLoad) {\r\n\t\t\t\treturn;\r\n\t\t\t}\r\n\r\n\t\t\tconst themeValue = ThemeConfigConstants.themesDic[picked!];\r\n\t\t\tif (!themeValue) {\r\n\t\t\t\treturn;\r\n\t\t\t}\r\n\r\n\t\t\tthemeLink.href = picked!;\r\n\t\t\tthis.selectedTheme = picked!;\r\n\t\t\tconsole.info(`theme altered to ${picked}.`);\r\n\r\n\t\t\tif (this.settings.appColorsLinkId) {\r\n\t\t\t\tlet appColorsLink = document.getElementById(this.settings.appColorsLinkId) as HTMLLinkElement;\r\n\t\t\t\tif (appColorsLink) {\r\n\t\t\t\t\tif (themeValue.dark != null && this.settings.colorsDarkCss && this.settings.colorsCss) {\r\n\t\t\t\t\t\tconst customFile = themeValue.dark ? this.settings.colorsDarkCss : this.settings.colorsCss;\r\n\t\t\t\t\t\tappColorsLink.href = (this.settings.appColorsDir ?? '') + customFile;\r\n\t\t\t\t\t} else if (this.settings.colorsCss) {\r\n\t\t\t\t\t\tappColorsLink.href = (this.settings.appColorsDir ?? '') + this.settings.colorsCss;\r\n\t\t\t\t\t}\r\n\t\t\t\t}\r\n\t\t\t}\r\n\t\t} else { // when app is loaded for the first time, then create \r\n\t\t\tthemeLink = document.createElement('link');\r\n\t\t\tthemeLink.id = this.settings.themeLinkId;\r\n\t\t\tthemeLink.rel = 'stylesheet';\r\n\t\t\tconst themeDicKey = picked ?? Object.keys(ThemeConfigConstants.themesDic!)[0];\r\n\t\t\tthemeLink.href = themeDicKey;\r\n\t\t\tdocument.head.appendChild(themeLink);\r\n\t\t\tthis.selectedTheme = themeDicKey;\r\n\t\t\tconsole.info(`Initially loaded theme ${themeDicKey}`);\r\n\r\n\t\t\tif (this.settings.appColorsLinkId) {\r\n\t\t\t\tconst appColorsLink = document.createElement('link');\r\n\t\t\t\tappColorsLink.id = this.settings.appColorsLinkId;\r\n\t\t\t\tappColorsLink.rel = 'stylesheet';\r\n\t\t\t\tconst themeValue = ThemeConfigConstants.themesDic[themeDicKey];\r\n\t\t\t\tif (themeValue.dark != null && this.settings.colorsDarkCss && this.settings.colorsCss) {\r\n\t\t\t\t\tconst customFile = themeValue.dark ? this.settings.colorsDarkCss : this.settings.colorsCss;\r\n\t\t\t\t\tappColorsLink.href = (this.settings.appColorsDir ?? '') + customFile;\r\n\t\t\t\t} else if (this.settings.colorsCss) {\r\n\t\t\t\t\tappColorsLink.href = (this.settings.appColorsDir ?? '') + this.settings.colorsCss;\r\n\t\t\t\t}\r\n\r\n\t\t\t\tif (appColorsLink.href) {\r\n\t\t\t\t\tdocument.head.appendChild(appColorsLink);\r\n\t\t\t\t\tconsole.info(`appColors ${appColorsLink} loaded.`)\r\n\t\t\t\t} else {\r\n\t\t\t\t\tconsole.warn(`With appColorsLinkId defined, dark&colorsCss&colorDarkCss or colorsCss should be defined.`)\r\n\t\t\t\t}\r\n\t\t\t}\r\n\t\t}\r\n\t}\r\n}\r\n","/*\r\n * Public API Surface of theme-loader-api\r\n */\r\n\r\nexport * from './lib/themeDef';\r\nexport * from './lib/themeLoader';\r\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "theme-loader-api",
+  "version": "1.0.0",
+  "author": {
+    "name": "Z"
+  },
+  "description": "Theme loader API independent of framework, lib and UI design of Web app.",
+  "license": "MIT",
+  "repository": {
+    "url": "git+https://github.com/zijianhuang/nmce.git"
+  },
+  "keywords": [
+    "theme",
+    "angular",
+    "react",
+    "vue",
+    "web"
+  ],
+  "peerDependencies": {},
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/theme-loader-api.mjs",
+  "typings": "types/theme-loader-api.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/theme-loader-api.d.ts",
+      "default": "./fesm2022/theme-loader-api.mjs"
+    }
+  }
+}

package/types/theme-loader-api.d.ts

@@ -0,0 +1,76 @@
+interface ThemeValue {
+    /** Display name used in the UI like menu or dropdown */
+    display: string;
+    /** Dark them or not. Optionally to tell which optional app level colors CSS to use, if some app level colors need to adapt the light or dark theme. */
+    dark?: boolean;
+}
+interface ThemeDef extends ThemeValue {
+    /** Relative path or URL to CDN */
+    filePath: string;
+}
+interface ThemesDic {
+    [filePath: string]: ThemeValue;
+}
+interface ThemeLoaderSettings {
+    /**
+     * The key of themeDic to store the selected theme in local storage of browser. Each app or site must have a unique key to avoid conflict with other apps or sites.
+     */
+    storageKey: string;
+    /**
+     * The id of the link element in index.html for loading the theme CSS file dynamically during app startup and operation.
+     */
+    themeLinkId: string;
+    /**
+     * Optionally the app may has an app level colors CSS declaring colors neutral to the light or dark theme, in addition to a prebuilt theme reused across apps.
+     * If some colors need to adapt the light or dark theme, having those colors defined in colorsCss and colorsDarkCss is convenient for SDLC, since you can
+     * use tools to flip colors to dark or light.
+     */
+    appColorsLinkId?: string;
+    /**
+     * If undefined or null, app colors css is in root.
+     * Effected only when appColorsLinkId is defined.
+     */
+    appColorsDir?: string;
+    /**
+     * Optionally the app may has an app level colors CSS declaring colors adapting to the light theme.
+     * If the app uses only light or dark theme, for example ThemeValue.dark is not defined, this alone is enough, not needing colorsDarkCss.
+    */
+    colorsCss?: string;
+    /**
+     * Optionally the app may has an app level colors CSS declaring colors adapting to the dark theme.
+     * If the app uses only light or dark theme, there's no need to declare this.
+     */
+    colorsDarkCss?: string;
+}
+interface Theme_Config {
+    themesDic?: ThemesDic;
+    themeLoaderSettings?: ThemeLoaderSettings;
+}
+declare const ThemeConfigConstants: Theme_Config;
+
+/**
+ * Helper class to load default theme or selected theme among themes defined in app startup settings.
+ * index.html should not have the theme css link during design time.
+ * In addition to the main theme which could be one the prebuilt themes reusable across apps, like one of those of Angular Material,
+ * the app may optionally has its own app css file for colors.
+ */
+declare class ThemeLoader {
+    private static readonly settings;
+    /**
+     * selected theme file name saved in localStorage.
+     */
+    static get selectedTheme(): string | null;
+    private static set selectedTheme(value);
+    /**
+     * Load default or previously selected theme during app startup, typically used before calling `bootstrapApplication()`.
+     */
+    static init(): void;
+    /**
+     * Load theme during operation through `ThemeLoader.loadTheme(themeDicKey);`.
+     * @param picked one of the prebuilt themes, typically used with the app's theme picker.
+     */
+    static loadTheme(picked: string | null): void;
+}
+
+export { ThemeConfigConstants, ThemeLoader };
+export type { ThemeDef, ThemeLoaderSettings, ThemeValue, ThemesDic };