Merge pull request #4 from basher/themes

Setup architecture for theming

README.md

@@ -13,49 +13,60 @@ Just plain vanilla code. 😜
 - Live Storybook URL = https://basher.github.io/Web-UI-Boilerplate/
 
 ## Compile and watch for UI changes
-> - Use the correct Node version as listed in `ui/.nvmrc`. If necessary, install Node Version Manager (NVM).
+> NOTE: Use the correct Node version as listed in `ui/.nvmrc`. If necessary, install Node Version Manager (NVM).
 
 Run both the following commands in **separate terminal instances** in order to be able to compile CSS/JavaScript and test the UI in Storybook.
 
 From `ui` directory:
-- `npm start` - Installs Node modules (if not already installed) and launches Parcel bundler.
+- `npm run start:theme --theme=[theme-name]` - Installs Node modules (if not already installed), launches Parcel bundler to compile/watch files (using the specified theme), and sets the port for HMR (Hot Module Reloading) to work in Storybook.
 - `npm run storybook` - Launches Storybook/HTML component library.
 
+### UI themes
+- Theme-specific CSS is located in `ui/src/css/_THEMES` folder.
+- Valid UI theme names are located in `ui/scripts/theme-config.js`.
+- To change the theme in `DEV MODE`, stop the Parcel Node process with `CTRL+C`, and start new theme with `npm run start:theme --theme=[theme-name]`.
+- This uses an NPM config variable in `ui/.npmrc`.
+- The new theme will be loaded in Storybook.
+
 ## Bundle CSS/JavaScript for production without watch
 From `ui` directory:
-- `npm run build`
+- `npm run build:theme --theme=[theme-name]` - Compiles and minifies files, for production and local dev environments.
+- `npm run bundle-all-themes` - Bundles ALL themes.
 
 ## Local DEV environment (for example, .Net, PHP)
-In order to use the bundled CSS/JavaScript in `localhost`, both `npm start` and `npm run storybook` need to be run.
+In order to use the bundled CSS/JavaScript in `localhost`, both `npm start:theme...` and `npm run storybook` need to be run.
 
 However, these can be concatenated together into a single background task so that the Storybook application doesn't need to be actually loaded in the browser.
 
 ### Linking to compiled CSS/JavaScript
-There is a difference between `development` and `production` environments in terms of the locations of the compiled CSS/JavaScript.
+- There is a difference between `development` and `production` environments in terms of the locations of the compiled CSS/JavaScript.
+- The `<link>` and `<script>` tags in `ui/.storybook/preview-head.html` use placeholders, which reference environment variables defined in `ui/.env` files:
 
-#### DEVELOPMENT
-Uses the Storybook dev server.
 ```
-<link rel="stylesheet" href="http://localhost:6006/index.css">
+<link href="%STORYBOOK_CSS_PATH%" rel="stylesheet" />
+<script defer src="%STORYBOOK_JS_PATH%"></script>
 ```
+
+#### DEVELOPMENT
+Uses the Storybook dev server, with paths defined in `ui/.env.development`:
 ```
-<script src="http://localhost:6006/index.js"></script>
+STORYBOOK_CSS_PATH=index.css
+STORYBOOK_JS_PATH=index.js
 ```
 
 #### PRODUCTION
-Uses whatever build folder has been defined for the web application.
+Uses whatever build folder has been defined for the website / web application in `ui/.env.production`:
 ```
-<link rel="stylesheet" href="/path/to/build/folder/stylesheets/index.css">
-```
-```
-<script defer type="module" src="/path/to/build/folder/javascript/index.js"></script>
-<script defer nomodule src="/path/to/build/folder/javascript/legacy.js"></script>
+STORYBOOK_CSS_PATH=build/ui/default/css/index.css
+STORYBOOK_JS_PATH=build/ui/default/javascript/index.js
 ```
 
 ## Build and publish Storybook
 From `ui` directory:
-- `npm run publish-storybook` - this runs a Parcel build to bundle CSS/JavaScript in the `public` folder, as defined in `ui/.storybook/main.js`.
-- `npx http-server ./storybook-static` - to test production build on local server.
+- `npm run publish-storybook` - Runs Parcel build (using the `default` theme) to bundle CSS/JS in the `public` folder, which then gets copied to `storybook-static` folder.
+- `npx http-server ./storybook-static` - Test production build on local server.
+
+> NOTE: ALL themes are actually bundled, but only the default theme is rendered in Storybook.
 
 ### Publish using GitHub pages
 - Uses the workflow defined in `.github/workflows/static.yml`.
@@ -67,3 +78,8 @@ From `ui` directory:
 ## Additional required files in project root directory
 - `.vscode/settings.json` defines the correct working directory for `.eslintignore` and `.stylelintrc`.
 - `.editorconfig` ensures all code uses the same indentation.
+
+## TODO
+- Override theme fonts.
+- Override a component partial.
+- Add theme switcher to Storybook.

ui/.env.development

@@ -0,0 +1,2 @@
+STORYBOOK_CSS_PATH=index.css
+STORYBOOK_JS_PATH=index.js

ui/.env.production

@@ -0,0 +1,2 @@
+STORYBOOK_CSS_PATH=build/ui/default/css/index.css
+STORYBOOK_JS_PATH=build/ui/default/javascript/index.js

ui/.npmrc

@@ -0,0 +1,2 @@
+# Config variable. Allows theme to be passed as NPM script param.
+web-ui-boilerplate:theme=default

ui/.storybook/preview-head.html

@@ -1,8 +1,8 @@
 <meta name="robots" content="noindex, nofollow">
 
 <!-- Load CSS/JS that Parcel has bundled. -->
-<link href="index.css" rel="stylesheet" />
-<script defer src="index.js"></script>
+<link href="%STORYBOOK_CSS_PATH%" rel="stylesheet" />
+<script defer src="%STORYBOOK_JS_PATH%"></script>
 
 <!-- Overrides for Storybook Docs and UI. -->
 <link href="storybook-overrides.css" rel="stylesheet" />

ui/README.md

@@ -1,11 +1,11 @@
 # Web UI Boilerplate - the actual 'UI' code
 
-## Useful commands
+## Useful commands recap (described fully in project root README)
 From `ui` directory:
-- `npm run reset` - Deletes `node_modules` folder and reinstalls with `npm run install`.
-- `npm start` - Installs Node modules (if not already installed), launches Parcel bundler to compile/watch files, and sets the port for HMR (Hot Module Reloading) to work in Storybook.
-- `npm run storybook` - Launches Storybook/HTML component library. Run this in a different terminal instance to Parcel.
-- `npm run build` - Compiles and minifies files, for production and local dev environments.
+- `npm run start:theme --theme=[theme-name]`
+- `npm run storybook`
+- `npm run build:theme --theme=[theme-name]`
+- `npm run bundle-all-themes`
 
 ## Code authoring guidelines & accessibility
 - All UI components are authored with **semantic HTML5** markup, which is **progressively enhanced** with JavaScript and `WAI-ARIA` as appropriate.
@@ -57,7 +57,7 @@ Configured using `husky` and `lint-staged` to ensure no linting errors are commi
 ```
 "start:parcel": "parcel watch src/javascript/index.ts --hmr-port 1234 --target app"
 ```
-- This command does not need to be explicitly run as `npm start` does it for you.
+- This command does not need to be explicitly run as `npm run start:theme...` does it for you.
 - See the `HMR` section further down for an explanation of the `--hmr-port 1234` argument.
 - The `--target app` argument enables transpilation of both CSS and JavaScript in **local DEV mode**. By default, Parcel only does this for production builds.
 
@@ -96,4 +96,4 @@ Configured using `husky` and `lint-staged` to ensure no linting errors are commi
 ## Trouble-shooting bundling and build issues
 - If bundling breaks, or UI is not updated (in DEV mode) to reflect latest CSS/JavaScript changes:
     - Kill the Parcel Node process with `CTRL+C`.
-    - Run `npm start` again.
+    - Run `npm run start:theme...` again.