@lipemat/js-boilerplate 8.4.0 → 8.6.0-beta.2

package/README.md

@@ -21,7 +21,6 @@ Add the following to your package.json. (this may also be found in the `template
 ```json
 {
   "jsPath": "./js",
-  "themeUrlPath": "/wp-content/themes/core/",
   "scripts": {
     "browserslist": "lipemat-js-boilerplate browserslist",
     "dist": "lipemat-js-boilerplate dist",
@@ -39,8 +38,8 @@ Add the following to your package.json. (this may also be found in the `template
 ```
 **_You may adjust things as needed but be sure to leave the `scripts` as is._**
 
+* `shortCssClasses`: Enable short 1-2 character CSS classes. Recommended if you're not running multiple instances of this package on the same site.
 * `jsPath`: Path of JS application relative to `package.json`. If `package.json` is in same directory as the JS application, this may be omitted.
-* `themeUrlPath`: Path of `package.json` file relative to site's domain.
 
 ## Code Completion In PHPStorm
 Some `@types` have been specified in this library to assist with code completion and allow using the built-in TypeScript support. Unfortunately, some typescripts still send errors to PHPStorm like "Default export is not declared in an imported module". I've found that it's easier to just remove this warning by un-checking `Editor -> Inspections -> JavaScript -> General -> Validate Imports`. (this may not need to be un-checked if you enable the built-in TypeScript support).

package/config/css-loader.config.js

@@ -0,0 +1,44 @@
+const config = require( '../helpers/package-config' );
+const {getLocalIdent} = require( '../helpers/css-classnames' );
+
+/**
+ * Options for the Webpack `css-loader`.
+ *
+ * Extracted to its on file to allow easy overrides.
+ *
+ * @since 8.6.0
+ */
+
+let cssLoader = {
+	importLoaders: 1,
+	modules: {
+		exportLocalsConvention: 'camelCase',
+		localIdentName: 'Ⓜ[name]__[local]__[contenthash:base64:2]',
+		// Default to :global for classes in "global" directories.
+		mode: resourcePath => {
+			return /globals?\//i.test( resourcePath.replace( /\\/g, '/' ) ) ? 'global' : 'local';
+		},
+	},
+	sourceMap: true,
+	url: false,
+};
+
+if ( 'production' === process.env.NODE_ENV ) {
+	cssLoader = {
+		importLoaders: 1,
+		modules: {
+			exportLocalsConvention: 'camelCase',
+			// Use short CSS Classes if enabled.
+			...config.shortCssClasses ? {getLocalIdent} : {},
+			// Hash used when short CSS classes are not enabled.
+			localIdentName: '[contenthash:base64:5]',
+			// Default to :global for classes in "global" directories.
+			mode: resourcePath => {
+				return /globals?\//i.test( resourcePath.replace( /\\/g, '/' ) ) ? 'global' : 'local';
+			},
+		},
+		url: false,
+	};
+}
+
+module.exports = cssLoader;

package/config/jest.config.js

@@ -14,6 +14,9 @@ let jestConfig = {
 	moduleNameMapper: {
 		'\\.(pcss|less|css)$': 'identity-obj-proxy',
 	},
+	roots: [
+		'./tests',
+	],
 	testURL: packageConfig.url,
 	transform: {
 		'^.+\\.[tj]sx?$': [ 'babel-jest', babelConfig ],

package/config/postcss.config.js

@@ -64,7 +64,7 @@ const config = {
 	parser: 'postcss-scss',
 };
 
-// For production we minify it.
+// For production, we minify it.
 if ( 'production' === process.env.NODE_ENV ) {
 	config.plugins.push( require( '../lib/postcss-clean' )( {
 		level: 2,

package/config/webpack.dev.js

@@ -1,11 +1,13 @@
+const {getConfig, hasLocalOverride} = require( '../helpers/config' );
 const webpack = require( 'webpack' );
 const path = require( 'path' );
 const fs = require( 'fs' );
-const configHelper = require( '../helpers/config' );
 const ForkTsCheckerWebpackPlugin = require( 'fork-ts-checker-webpack-plugin' );
 const config = require( '../helpers/package-config' );
-const postCSSOptions = configHelper.getConfig( 'postcss.config.js' );
-const babelOptions = configHelper.getConfig( 'babel.config.js' );
+
+const postCSSOptions = getConfig( 'postcss.config.js' );
+const babelOptions = getConfig( 'babel.config.js' );
+const cssLoaderOptions = getConfig( 'css-loader.config.js' );
 
 // To allow line numbers to show up in console errors. @see React Error Boundaries.
 babelOptions.plugins.unshift( '@babel/plugin-transform-react-jsx-source' );
@@ -19,7 +21,7 @@ const plugins = [
 
 // Loads a thread, which verifies any TypeScripts on changes.
 // Only use this if the project has a tsconfig.json file.
-if ( configHelper.hasLocalOverride( 'tsconfig.json', true ) ) {
+if ( hasLocalOverride( 'tsconfig.json', true ) ) {
 	plugins.push( new ForkTsCheckerWebpackPlugin( {
 		formatter: 'basic',
 		logger: {
@@ -92,19 +94,7 @@ module.exports = {
 					'style-loader',
 					{
 						loader: 'css-loader',
-						options: {
-							importLoaders: 1,
-							modules: {
-								exportLocalsConvention: 'camelCase',
-								localIdentName: 'Ⓜ[name]__[local]__[contenthash:base64:2]',
-								// Default to :global for classes in "global" directories.
-								mode: resourcePath => {
-									return /globals?\//i.test( resourcePath.replace( /\\/g, '/' ) ) ? 'global' : 'local';
-								},
-							},
-							sourceMap: true,
-							url: false,
-						},
+						options: cssLoaderOptions,
 					},
 					{
 						loader: '@lipemat/postcss-loader',

package/config/webpack.dist.js

@@ -1,14 +1,18 @@
+const {getConfig} = require( '../helpers/config' );
 const moduleHelpers = require( '../helpers/modules' );
 const webpack = require( 'webpack' );
 const path = require( 'path' );
 const fs = require( 'fs' );
 const MiniCssExtractPlugin = require( 'mini-css-extract-plugin' );
 const WebpackCleanupPlugin = require( '@lipemat/webpack-cleanup-plugin' );
-const config = require( '../helpers/package-config' );
-const postCSSOptions = require( '../helpers/config' ).getConfig( 'postcss.config.js' );
-const babelOptions = require( '../helpers/config' ).getConfig( 'babel.config.js' );
 const WebpackAssetsManifest = require( 'webpack-assets-manifest' );
 const SriPlugin = require( 'webpack-subresource-integrity' );
+const config = require( '../helpers/package-config' );
+
+const postCSSOptions = getConfig( 'postcss.config.js' );
+const babelOptions = getConfig( 'babel.config.js' );
+const cssLoaderOptions = getConfig( 'css-loader.config.js' );
+
 
 const entry = {
 	master: [
@@ -55,7 +59,7 @@ module.exports = {
 	output: {
 		path: path.resolve( config.workingDirectory, 'dist' ),
 		filename: '[name].js',
-		publicPath: config.themeUrlPath + 'js/dist/',
+		publicPath: 'auto', // Change this if you want to use an external CDN etc.
 		chunkFilename: '[name].[chunkhash].js',
 		crossOriginLoading: 'anonymous',
 	},
@@ -72,7 +76,7 @@ module.exports = {
 			$: 'jquery',
 		} ),
 		new MiniCssExtractPlugin( {
-			filename: 'master.css',
+			filename: '[name].css',
 			chunkFilename: '[name].[chunkhash].css',
 		} ),
 		new WebpackCleanupPlugin(),
@@ -98,18 +102,7 @@ module.exports = {
 					MiniCssExtractPlugin.loader,
 					{
 						loader: 'css-loader',
-						options: {
-							importLoaders: 1,
-							modules: {
-								exportLocalsConvention: 'camelCase',
-								localIdentName: '[contenthash:base64:5]',
-								// Default to :global for classes in "global" directories.
-								mode: resourcePath => {
-									return /globals?\//i.test( resourcePath.replace( /\\/g, '/' ) ) ? 'global' : 'local';
-								},
-							},
-							url: false,
-						},
+						options: cssLoaderOptions,
 					},
 					{
 						loader: '@lipemat/postcss-loader',

package/helpers/css-classnames.js

@@ -0,0 +1,106 @@
+const SHORT_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+const ALPHABET = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+
+const classes = {};
+let counters = [ -1 ];
+
+/**
+ * Reset all counters.
+ *
+ * @notice Mostly here for unit tests.
+ */
+function resetCounters() {
+	counters = [ -1 ];
+}
+
+/**
+ * Get the next class is sequence based on:
+ * 1. Single character from SHORT_ALPHABET (prevent conflicts with CSS boilerplate).
+ * 2. Incremented character from the `ALPHABET`.
+ *      1. Used once require 2+ characters.
+ *      2. Grows to 3+ characters as needed.
+ *
+ * @return {string}
+ */
+function getNextClass() {
+	const last = counters.length - 1;
+	let totalLetters = ALPHABET.length - 1;
+
+	// First level uses the SHORT_ALPHABET.
+	if ( 0 === last ) {
+		totalLetters = SHORT_ALPHABET.length - 1;
+	}
+
+	if ( counters[ last ] < totalLetters ) {
+		counters[ last ]++;
+	} else {
+		incrementParent();
+	}
+
+	return counters.map( ( counter, i ) => {
+		return 0 === i ? SHORT_ALPHABET[ counter ] : ALPHABET[ counter ];
+	} ).join( '' );
+}
+
+
+/**
+ * When we run out of characters on the current level:
+ * 1. Increment the parent level.
+ * 2. Reset current level and all child levels back to 0.
+ *
+ * If we are out of characters on the parent level or have
+ * no parent level:
+ * 1. Add a new child level.
+ * 2. Reset all levels back to 0.
+ *
+ */
+function incrementParent() {
+	let parent = counters.length - 2;
+	let totalLetters = ALPHABET.length - 1;
+
+	while ( counters[ parent ] !== undefined ) {
+		// First level uses the SHORT_ALPHABET.
+		if ( 0 === parent ) {
+			totalLetters = SHORT_ALPHABET.length - 1;
+		}
+		if ( counters[ parent ] < totalLetters ) {
+			counters[ parent ]++;
+			// Reset all child levels to 0.
+			while ( counters[ parent + 1 ] !== undefined ) {
+				counters[ parent + 1 ] = 0;
+				parent++;
+			}
+			return;
+		}
+		parent--;
+	}
+
+	// Add a new level and reset all existing levels.
+	counters.forEach( ( _, i ) => counters[ i ] = 0 );
+	counters.push( 0 );
+}
+
+/**
+ * Return a single character unique CSS class name based on WebPack
+ * css-loader's `getLocalIdentName` callback.
+ *
+ * Tracks CSS classes per each file so duplicate uses of the
+ * same class in a file receive the same result.
+ *
+ * @notice Only enabled if the `package.json` has `shortCssClasses` set to true.
+ *
+ * @link https://webpack.js.org/loaders/css-loader/#getlocalident
+ */
+const getLocalIdent = ( {resourcePath}, _, localName ) => {
+	classes[ resourcePath ] ||= {};
+	classes[ resourcePath ][ localName ] ||= getNextClass();
+	return classes[ resourcePath ][ localName ];
+};
+
+module.exports = {
+	ALPHABET,
+	SHORT_ALPHABET,
+	getLocalIdent,
+	getNextClass,
+	resetCounters,
+};

package/helpers/package-config.js

@@ -1,18 +1,16 @@
-/**
- * Get all configurations for package.json of the project running this.
- */
 const path = require( 'path' );
 const fs = require( 'fs' );
-const workingDirectory = fs.realpathSync( process.cwd() );
 
+const workingDirectory = fs.realpathSync( process.cwd() );
 let packageConfig = require( path.resolve( workingDirectory, 'package.json' ) );
-packageConfig.es6Modules = packageConfig.es6Modules || [];
+packageConfig.es6Modules ||= [];
+packageConfig.jsPath ||= '';
 // Path of the package.json file (root).
 packageConfig.packageDirectory = workingDirectory;
-packageConfig.themeUrlPath = packageConfig.themeUrlPath || '/';
-packageConfig.url = packageConfig.url || 'http://localhost';
+packageConfig.url ||= 'http://localhost';
 // Path of JS application files.
-packageConfig.workingDirectory = packageConfig.jsPath ? path.resolve( packageConfig.jsPath ) : workingDirectory;
+packageConfig.workingDirectory = packageConfig.jsPath !== '' ? path.resolve( packageConfig.jsPath ) : workingDirectory;
+packageConfig.shortCssClasses ||= false;
 
 try {
 	const localConfig = require( path.resolve( workingDirectory, './local-config.json' ) );

package/package.json

@@ -1,14 +1,21 @@
 {
   "name": "@lipemat/js-boilerplate",
-  "version": "8.4.0",
+  "version": "8.6.0-beta.2",
   "description": "Dependencies and scripts for a no config JavaScript app",
+  "author": "Mat Lipe",
+  "license": "MIT",
   "engines": {
     "node": ">=14.17.6"
   },
+  "bugs": {
+    "url": "https://github.com/lipemat/js-boilerplate/issues"
+  },
+  "homepage": "https://github.com/lipemat/js-boilerplate#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lipemat/js-boilerplate.git"
   },
+  "sideEffects": false,
   "keywords": [
     "react",
     "boilerplate",
@@ -25,9 +32,9 @@
   "bin": {
     "lipemat-js-boilerplate": "bin/lipemat-js-boilerplate.js"
   },
-  "author": "Mat Lipe",
-  "license": "MIT",
-  "sideEffects": false,
+  "scripts": {
+    "test": "lipemat-js-boilerplate test --silent"
+  },
   "dependencies": {
     "@babel/core": "^7.4.3",
     "@babel/plugin-syntax-dynamic-import": "^7.8.3",
@@ -81,9 +88,5 @@
     "webpack-dev-server": "^4.7.2",
     "webpack-subresource-integrity": "^1.5.2"
   },
-  "bugs": {
-    "url": "https://github.com/lipemat/js-boilerplate/issues"
-  },
-  "homepage": "https://github.com/lipemat/js-boilerplate#readme",
   "packageManager": "yarn@3.2.0"
 }