theme-loader-api 1.0.0 → 1.0.1

package/README.md

@@ -1,3 +1,13 @@
+### Web Sites and Apps that Use This ThemeLoader
+
+* [Angular Material Components Extension](https://zijianhuang.github.io/nmce/en/)
+* [JsonToTable](https://zijianhuang.github.io/json2table/)
+* [Personal Blog](https://zijianhuang.github.io/poets)
+* [Angular Heroes](https://zijianhuang.github.io/DemoCoreWeb/angular/dashboard), and [Sourcecode](https://github.com/zijianhuang/DemoCoreWeb/tree/master/AngularHeroes)
+* [React Heroes](https://zijianhuang.github.io/DemoCoreWeb/react/) and [Sourcecode](https://github.com/zijianhuang/DemoCoreWeb/tree/master/ReactHeroes)
+
+![MatSelect](https://zijianhuang.github.io/articles/Web%20Theme%20Loader%20Tips/media/MatSelect.png)![ThemeMenu](https://zijianhuang.github.io/articles/Web%20Theme%20Loader%20Tips/media/themeMenu.png)![ThemeMenuNG](https://zijianhuang.github.io/articles/Web%20Theme%20Loader%20Tips/media/themeMenuNM.png)
+
 ## Summary
 
 The Web theme loader API exposes 3 contracts:
@@ -10,19 +20,22 @@ Because the theme should be loaded at startup before the Web app rendering, the
 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:
+* 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 want your Website or Webapp to adapt such preference automatically and do not expect users to change theme, then CSS only solution works well without using JavaScript code:
 ```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).
+1. Install [theme-loader-api](https://www.npmjs.com/package/theme-loader-api):
+```
+npm install 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.
+1. Call `ThemeLoader.loadTheme()` before the [bootstrap of the Web app](https://github.com/zijianhuang/DemoCoreWeb/blob/master/AngularHeroes/src/main.ts).
+1. In the [UI component presenting the theme picker](https://github.com/zijianhuang/DemoCoreWeb/blob/master/AngularHeroes/src/app/theme-select.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://zijianhuang.github.io/DemoCoreWeb/react/conf/siteconfig.js) and add `<script src="conf/siteconfig.js"></script>` to [index.html](https://github.com/zijianhuang/DemoCoreWeb/blob/master/ReactHeroes/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/)
 
@@ -35,8 +48,8 @@ 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];
+		this.themes = ThemeConfigConstants.themesDic ? Object.keys(ThemeConfigConstants.themesDic).map(k => {
+			const c = ThemeConfigConstants.themesDic![k];
 			const obj: ThemeDef = {
 				display: c.display,
 				filePath: k,
@@ -63,7 +76,6 @@ bootstrapApplication(AppComponent, appConfig);
 [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 },
@@ -89,7 +101,7 @@ const THEME_CONFIG = {
 
 ### React Example
 
-[index.tsx](https://github.com/zijianhuang/DemoCoreWeb/blob/master/ReactHeroes/src/index.tsx)
+[main.tsx](https://github.com/zijianhuang/DemoCoreWeb/blob/master/ReactHeroes/src/main.tsx)
 ```ts
 ThemeLoader.init();
 
@@ -101,8 +113,8 @@ 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 themes = ThemeConfigConstants.themesDic ? Object.keys(ThemeConfigConstants.themesDic).map(k => {
+		const c = ThemeConfigConstants.themesDic![k];
 		const obj: ThemeDef = {
 			display: c.display,
 			filePath: k,
@@ -140,7 +152,6 @@ root.render(...
 [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 },
@@ -158,7 +169,7 @@ const THEME_CONFIG = {
 }
 ```
 
-[index.html](https://github.com/zijianhuang/DemoCoreWeb/blob/master/ReactHeroes/public/index.html)
+[index.html](https://github.com/zijianhuang/DemoCoreWeb/blob/master/ReactHeroes/index.html)
 ```html
     <script src="conf/siteconfig.js"></script>
 </head>
@@ -166,7 +177,7 @@ const THEME_CONFIG = {
 
 ### 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:
+By default, this API will pick the first available theme in the dictionary during the first startup of the Web app, and use 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);
@@ -178,15 +189,12 @@ platformBrowser().bootstrapModule(AppModule, { applicationProviders: [provideZon
 	.catch(err => console.error(err));
 
 function findFirstTheme(dark: boolean): { filePath: string; theme: ThemeValue } | undefined {
-	const entry = Object.entries(AppConfigConstants.themesDic!).find(
+	const entry = Object.entries(ThemeConfigConstants.themesDic!).find(
 		([, theme]) => theme.dark === dark
 	);
 
-	return entry
-		? { filePath: entry[0], theme: entry[1] }
-		: undefined;
+	return entry ? { filePath: entry[0], theme: entry[1] } : undefined;
 }
-
 ```
 
 ## How About I18N and L10N?
@@ -197,7 +205,7 @@ The only things need to be translated is the display name of each theme.
 
 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.
+Or you may just hand-draw some SVG icons and linked them in the HTML template.
 
 ### Solution 2: Create Dictionary in App Code
 
@@ -205,6 +213,6 @@ Depending the framework like Angular or the library like React, there could be a
 
 ### 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. 
+If you are using `siteconfig.js`, the JS file should not be included in the hash tables of the service worker for automatic app 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/package.json

@@ -1,20 +1,27 @@
 {
   "name": "theme-loader-api",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "author": {
     "name": "Z"
   },
   "description": "Theme loader API independent of framework, lib and UI design of Web app.",
   "license": "MIT",
+  "homepage": "https://github.com/zijianhuang/nmce/tree/master/projects/theme-loader-api#readme",
   "repository": {
-    "url": "git+https://github.com/zijianhuang/nmce.git"
+    "type": "git",
+    "url": "https://github.com/zijianhuang/nmce.git",
+    "directory": "projects/theme-loader-api"
   },
   "keywords": [
     "theme",
+    "theme-loader",
+    "theming",
+    "css",
+    "dark-mode",
     "angular",
     "react",
     "vue",
-    "web"
+    "framework-agnostic"
   ],
   "peerDependencies": {},
   "dependencies": {