@penskemediacorp/larva 1.2.0-alpha.0 → 1.3.0

package/lib/generateStatic.js

@@ -0,0 +1,133 @@
+const path = require( 'path' );
+const mkdirp = require( 'mkdirp' );
+const fs = require( 'fs-extra' );
+const chalk = require( 'chalk' );
+const axios = require( 'axios' );
+
+const getAppConfiguration = require( './utils/getAppConfiguration' );
+const copySyncHelper = require( './utils/copySyncHelper' );
+
+const assetsConfig = getAppConfiguration( 'assets' );
+const themeAssetsConfig = getAppConfiguration( 'themeAssets' );
+
+/**
+ * Generate Static HTML
+ *
+ * Given an array of pattern routes from the Larva server and
+ * a target build directory, use HTTP requests the get the HTML content
+ * of each route, and write the content to directory structure that
+ * mirrors the pattern routes.
+ *
+ * @param {array} routesArr  An array of routes in a pattern server, excluding the pattern source (i.e. larva or project).
+ *                           This is the result of getPatternRoutes.
+ * @param {string} buildPath A directory where the HTML files should be written.
+ * @param {function} done    A callback function to run when the site generation completes.
+ * @param {string} urlBase   The base URL for the pattern library e.g. 'http://localhost:3001/larva'.
+ *                           Pattern routes will be appended to this. Should not end in slash.
+ *
+ * @see {@link getPatternRoutes}.
+ */
+
+
+module.exports = function generateStatic( routesArr, buildPath, done, urlBase = 'http://localhost:3000/larva' ) {
+	const errors = [];
+
+	fs.mkdirpSync( buildPath );
+
+	// Copy assets from assets/build and assets/public
+	// to the static site build directory.
+	console.log( '\nCopying assets...\n')
+
+	// assets/public dir contains fonts and non-built things.
+	const publicAssetsSrc = ( () => {
+		let pubPath = path.join( assetsConfig.path, `public` );
+
+		// Fallback to assets in Larva
+		if ( ! fs.existsSync( pubPath ) ) {
+			pubPath = path.join( assetsConfig.path, 'public' )
+		}
+
+		return pubPath;
+	})();
+	const publicAssetsDest = path.join( buildPath, '../assets/public' );
+
+	const builtAssets = [
+		'js',
+		'css',
+		'tokens',
+		'images',
+		'svg'
+	];
+
+	builtAssets.forEach( item => {
+		const dest = path.join( buildPath, `../assets/build/${item}` );
+		const src = path.join( assetsConfig.path, `build/${item}` );
+
+		copySyncHelper( src, dest );
+	});
+
+	copySyncHelper( publicAssetsSrc, publicAssetsDest );
+
+	const themeAssetKeys = Object.keys( themeAssetsConfig );
+
+	themeAssetKeys.forEach( key => {
+		const src = themeAssetsConfig[key];
+		const dest = path.join( buildPath, `../assets/theme/${key}` );
+
+		copySyncHelper( src, dest );
+	});
+
+	// Build the site.
+	// Cycle through the list of routes and write the response
+	// to files.
+	console.log( '\nBuilding site...\n');
+
+	try {
+
+		const promises = routesArr.map( ( route ) => {
+
+			const dir = path.join( buildPath, route );
+			const url = `${urlBase}/${route}`;
+
+			return axios.get( url ).then( ( response ) => {
+
+				if ( 200 === response.status ) {
+					mkdirp.sync( dir );
+					fs.writeFileSync( `${dir}/index.html`, response.data );
+					console.log( `Built ${route}.` );
+				}
+
+			} ).catch( ( e ) => {
+
+				if ( 'ECONNREFUSED' === e.code ) {
+					process.exitCode = 1;
+				} else {
+					mkdirp.sync( dir );
+					fs.writeFileSync( `${dir}/index.html`, e.message );
+
+					console.log( chalk.yellow( `Error writing ${route}: ${e.message}.` ) );
+				}
+
+			});
+
+		} );
+
+		axios.all( promises ).then( () => {
+
+			if ( errors.length > 0 ) {
+				console.log( errors );
+			}
+
+			done( chalk.green( `\nSite built to build/html/${path.basename( buildPath )}. Check output for issues.\n` ) );
+
+		} ).catch( ( e ) =>  {
+
+			done( chalk.bold.red( e ) );
+
+		});
+
+	} catch ( e ) {
+		console.error( e );
+	}
+
+}

package/lib/server.js

@@ -0,0 +1,284 @@
+const path = require( 'path' );
+const express = require('express');
+const { marked } = require( 'marked' );
+const fs = require( 'fs' );
+const globby = require( 'globby' );
+
+const {
+	TwingEnvironment,
+	TwingLoaderFilesystem,
+	TwingFilter,
+	TwingFunction
+} = require('twing');
+
+const fontData = require( '../../larva-tokens/lib/font-data' );
+
+const getAppConfiguration = require('./utils/getAppConfiguration' );
+const getPatternPathsToLoad = require( './utils/getPatternPathsToLoad' );
+const getPatternData = require( './utils/getPatternData' );
+const getAllPatternsObj = require( './utils/getAllPatternsObj' );
+
+const app = express();
+
+const patternConfig = getAppConfiguration( 'patterns' );
+const brandConfig = getAppConfiguration( 'brand' );
+const assetsConfig = getAppConfiguration( 'assets' );
+const themeAssetsConfig = getAppConfiguration( 'themeAssets' );
+const twigPaths = getPatternPathsToLoad( patternConfig );
+
+let loader = new TwingLoaderFilesystem( twigPaths );
+
+// Add markdown filter
+const markdownFilter = new TwingFilter( 'markdown', ( string ) => {
+	if ( string ) {
+		return Promise.resolve( marked( string ) );
+	} else {
+		const noDocsMessage = '**This needs docs!** <br>Create a README.md in the pattern\'s directory and add details about using this pattern in markdown.';
+
+		return Promise.resolve( marked( noDocsMessage ) );
+	}
+});
+
+// Support `{{ item|markup }}` syntax for outputting escaped content within loops.
+const markupFilter = new TwingFilter(
+	'markup',
+	( string ) => Promise.resolve( string ),
+	{},
+	{ is_safe: ['html'] }
+);
+
+const kebabify = ( name ) => {
+	let kebabCase = [];
+
+	// TODO: find a more concise way of turning a string into an iterable
+	for (let i = 0; i < name.length; i++) {
+		let letter = name[i];
+		kebabCase[i] = letter;
+	}
+
+	return kebabCase.reduce( ( a, b ) => {
+		if ( '_' === b ) {
+			return a.toLowerCase() + '-';
+		}
+		return a.toLowerCase() + b.toLowerCase();
+	});
+};
+
+// TODO: Could be an array/iterator if the namespace can be extracted from the key, the larva.config API could
+// change to `patterns: { larva: /larva/path/here/, project: /project/path/here }`
+loader.addPath( patternConfig.larvaPatternsDir, 'larva' );
+
+if( fs.existsSync( patternConfig.projectPatternsDir ) ) {
+	loader.addPath( patternConfig.projectPatternsDir, 'project' );
+}
+
+let twing = new TwingEnvironment( loader, { debug: true } );
+
+twing.addFilter( markdownFilter );
+twing.addFilter( markupFilter );
+
+// Add custom function support for doing wp action: {{ wp_action( ... ) }}
+twing.addFunction(new TwingFunction('wp_action',() => {
+	// We're relying on twig-to-php-parser for translation, so just return empty string for now
+	return Promise.resolve('');
+}));
+
+let patterns = {
+	larva: getAllPatternsObj( patternConfig.larvaPatternsDir ),
+	project: getAllPatternsObj( patternConfig.projectPatternsDir )
+};
+
+// Use the project version if it exists, else use the larva version
+if ( fs.existsSync( assetsConfig.path ) ) {
+	app.use( '/assets' , express.static( assetsConfig.path ) );
+}
+
+// Expose any theme directories with assets in the express server
+const themeAssetKeys = Object.keys( themeAssetsConfig );
+
+themeAssetKeys.forEach( key => {
+	app.use( '/assets/theme/' + key , express.static( themeAssetsConfig[key] ) );
+});
+
+app.use( '/:source?/css', function (req, res) {
+
+	/**
+	 * Generate Larva CSS Docs
+	 *
+	 * (Something similar can be done for project CSS unless we eradicate it)
+	 *
+	 * 1. Get all CSS from the larva-css npm package.
+	 * 2. Use PostCSS to generate an abstract syntax tree.
+	 * 3. Generate a "spec" for the CSS by getting the base selector names
+	 *    from Sass files in larva-scss
+	 * 4. Walk the rules in the AST, checking the selectors against keys
+	 *    in the spec object, and adding them to an array of
+	 *    selectors for each property. Mark if it is in the hasTokens array.
+	 * 5. Send that spec object to the template.
+	 */
+
+	const postcss = require( 'postcss' );
+	const cssPath = path.join( process.cwd(), './node_modules/@penskemediacorp/larva/build/css/larva.css' );
+	const sassPath = path.join( process.cwd(), './node_modules/@penskemediacorp/larva-css/src/' );
+
+	const hasTokens = [
+		'u-background-color',
+		'u-border-color',
+		'u-color',
+		'u-font-family',
+		'u-letter-spacing',
+		'u-margin',
+		'u-padding',
+	];
+
+	const baseNames = ( () => {
+
+		let files = globby.sync( sassPath, {
+			expandDirectories: {
+				files: ['*.scss']
+			}
+		} );
+
+		return files.map( ( item ) => {
+			let parts = item.split( '/' );
+			let baseName = parts[ parts.length - 1 ].split( '.' );
+			return baseName[0];
+		} );
+	} )();
+
+	const cssString = fs.readFileSync( cssPath );
+
+	const cssRoot = postcss.parse( cssString )
+
+	const generatedSpec = ( () => {
+		let obj = {};
+
+		baseNames.forEach( ( item ) => {
+			obj[item] = {
+				selectors: [],
+				tokens: false
+			};
+		})
+
+		return obj;
+	} )();
+
+	cssRoot.walkRules( rule => {
+
+		Object.keys( generatedSpec ).forEach( key => {
+			let regex = new RegExp( '.*lrv-' + key + '.*', 'g' );
+
+			if ( -1 !== hasTokens.indexOf( key ) ) {
+				generatedSpec[key]['tokens'] = true;
+			}
+
+			if ( rule.selector.match( regex ) ) {
+				generatedSpec[key]['selectors'].push( rule.selector );
+			}
+
+		});
+
+	} );
+
+	req.params[ 'name' ] = 'Larva CSS';
+	req.params[ 'spec' ] = generatedSpec;
+
+	req.params[ 'source' ] = 'larva';
+	req.params[ 'pattern_nav' ] = patterns;
+
+	twing.render( 'css.html', req.params ).then( output => res.end( output ) );
+});
+
+app.get( '/:source/:type/:name/:variant?', function (req, res) {
+
+	let patternsPath;
+
+	if ( 'larva' === req.params.source ) {
+		patternsPath = patternConfig.larvaPatternsDir;
+	} else if ( 'project' === req.params.source ) {
+		patternsPath = patternConfig.projectPatternsDir;
+	} else if ( 'assets' === req.params.source ) {
+		return res.end();
+	}
+
+	// Support query parameters for conditionally loading stylesheets and scripts
+	req.params[ 'query' ] = req.query;
+	req.params[ 'pattern_nav' ] = patterns;
+	req.params[ 'data' ] = undefined !== patternsPath ? getPatternData( patternsPath, req.params ) : null;
+	req.params[ 'brand' ] = req.query.tokens ? req.query.tokens : brandConfig;
+	req.params[ 'variants' ] = patterns[req.params.source][req.params.type][req.params.name];
+
+	if ( 'algorithms' !== req.params.type ) {
+		req.params[ 'json_pretty' ] = JSON.stringify( req.params[ 'data' ], null, '\t' );
+	}
+
+	twing.render( 'pattern.html', req.params ).then( ( output ) => {
+		res.end( output );
+	}).catch( e => {
+		const errorMessage = `Cannot render template! \n\n${e}`;
+
+		console.log( e );
+
+		res.end( errorMessage );
+	} );
+});
+
+app.get( '/:source?/style-guide', function (req, res ) {
+
+	const brand = req.query.tokens ? req.query.tokens : brandConfig;
+	const tokensPath = path.join( assetsConfig.path, 'build/tokens' );
+
+	const tokensData = (() => {
+		try {
+			return require( path.join( tokensPath, `${brand}.json` ) );
+		} catch ( e ) {
+			return null;
+		}
+	})();
+
+	const colorsByProperty = ( () => {
+		if ( ! tokensData ) return;
+
+		const colorTokens = Object.keys( tokensData ).filter( item => item.includes( 'COLOR' ) );
+		const colorNames = colorTokens.map( token => kebabify( token ) );
+
+		return colorNames.reduce( (acc, curr) => {
+			Object.keys( acc ).forEach( key => {
+				if ( curr.startsWith( key ) ) {
+					acc[key].push( 'lrv-u-' + curr );
+				}
+			});
+
+			return acc;
+		}, {
+			color: [],
+			'background-color': [],
+			'border-color': []
+		});
+	})();
+
+	req.params[ 'name' ] = `Style Guide`;
+	req.params[ 'font_styles' ] = fontData.groupedSelectors;
+	req.params[ 'colors' ] = colorsByProperty;
+	req.params[ 'brand' ] = req.query.tokens ? req.query.tokens : brandConfig;
+	req.params[ 'pattern_nav' ] = patterns;
+
+	twing.render( 'style-guide/index.html', req.params ).then( output => res.end( output ) ).catch( e => {
+		const errorMessage = `Cannot render template! \n\n${e}`;
+
+		console.log( e );
+
+		res.end( errorMessage );
+	} );
+
+});
+
+app.get( '/:source?/:type?', function (req, res) {
+	req.params[ 'source' ] = 'larva';
+	req.params[ 'type' ] = req.params.type;
+	req.params[ 'pattern_nav' ] = patterns;
+	req.params[ 'brand' ] = req.query.tokens ? req.query.tokens : brandConfig;
+	twing.render( 'index.html', req.params ).then( output => res.end( output ) );
+});
+
+module.exports = app;

package/lib/start.js

@@ -0,0 +1,7 @@
+const app = require( './server' );
+
+const port = process.env.NODE_PORT || 3000;
+
+app.listen( port, () => {
+	console.log( 'Larva server is listening on port ' + port );
+});

package/lib/utils/clonePatternData.js

@@ -0,0 +1,13 @@
+const path = require( 'path' );
+const clonedeep = require( 'lodash.clonedeep' );
+const getConfig = require( './getAppConfiguration' );
+
+const { larvaPatternsDir, projectPatternsDir } = getConfig( 'patterns' );
+
+module.exports = function clonePatternData( slug ) {
+	try {
+		return clonedeep( require( path.join( projectPatternsDir, slug ) ) );
+	} catch {
+		return clonedeep( require( path.join( larvaPatternsDir, slug ) ) );
+	}
+}

package/lib/utils/copySyncHelper.js

@@ -0,0 +1,33 @@
+const path = require( 'path' );
+const fs = require( 'fs-extra' );
+const chalk = require( 'chalk' );
+
+/**
+ * copySync Helper
+ *
+ * Wrap the fs.copySync funtion and provide useful logging.
+ * See {@link https://github.com/jprichardson/node-fs-extra/blob/master/docs/copy-sync.md fs.copySync}.
+ *
+ * @param {string} src Path of directory or file to copy.
+ * @param {string} dest Path of destination for copied directory or file.
+ *
+ */
+
+module.exports = function copySyncHelper( src, dest ) {
+
+	const name = path.basename( src );
+
+	try {
+		fs.copySync( src, dest );
+
+		console.log( `Copied '${name}'.` );
+	} catch ( e ) {
+
+		if ( 'ENOENT' === e.code ) {
+			console.log( chalk.grey( `Can't find '${name}' to copy, skipping.` ) );
+		} else {
+			console.error( e );
+		}
+
+	}
+}

package/lib/utils/getAllPatternsObj.js

@@ -0,0 +1,48 @@
+const path = require( 'path' );
+const getAppConfiguration = require( './getAppConfiguration' );
+const getPatternVariants = require( './getPatternVariants' );
+const getSubDirectoryNames = require( './getSubDirectoryNames' );
+const getModuleNamesFromDirectory = require( './getModuleNamesFromDirectory' );
+
+const config = getAppConfiguration( 'patterns' );
+
+/**
+ * Get All Patterns
+ *
+ * Given a directory contianing patterns in the Larva structure (components/object/modules/one-offs),
+ * return an object representing all the pattern types, patterns, and their variants.
+ *
+ * @param {string} startPath - Path to look in for all patterns. Should be assets/src/patterns.
+ * @return {object} - Object representing all patterns and variants
+ */
+
+module.exports = function getAllPatternsObj( startPath ) {
+
+	const patternDirs = getSubDirectoryNames( startPath );
+
+	let obj = {};
+
+	try {
+		patternDirs.map( ( patternType ) => {
+			let patterns = [];
+			obj[patternType] = {};
+
+			// Modules can be ignored, which maybe is unecessary
+			// but for now continue on that path.
+			if ( 'modules' === patternType ) {
+				patterns = getModuleNamesFromDirectory( startPath, config.ignoredModules );
+			} else {
+				patterns = getSubDirectoryNames( path.join( startPath, patternType ) );
+			}
+
+			patterns.map( ( pattern ) => {
+				obj[patternType][pattern] = getPatternVariants( path.join( startPath, `${patternType}/${pattern}` ) );
+			} );
+
+		} );
+	} catch ( e ) {
+		console.error( e );
+	}
+
+	return obj;
+}

package/lib/utils/getAppConfiguration.js

@@ -0,0 +1,82 @@
+const fs = require( 'fs' );
+const path = require( 'path' );
+
+/**
+ * Get Larva Configuration
+ *
+ * Find larva.config.js according to the current working directory.
+ * For consuming projects, this will be theme/assets/, and for the
+ * mono-repo, it will be packages/larva.
+ *
+ * For test env, the CWD is overridden to the local directory for fixtures.
+ * (this is a problem for writing project-level tests, but for a later time.)
+ *
+ * @param {string} key string that indicates a specific configuration property, e.g. patterns.
+ * @param {boolean} usePackageDefault fall back to package default if not defined in app
+ *
+ * @return value of the specified key.
+ */
+
+const defaultConfig = {
+
+	eslint: {
+		configFile: path.join( __dirname, '../../scripts/config/.eslintrc.json' ),
+	},
+
+	webpack: {
+		aliases: {
+			'@js': path.resolve( './src/js' ),
+			'@npm': path.resolve( './node_modules' ),
+			'@larva-js': path.resolve( './node_modules/@penskemediacorp/larva-js/src' ),
+		},
+		entries: {
+			'larva-ui': path.resolve( './entries/larva-ui.entry.js' ),
+			common: path.resolve( './entries/common.entry.js' )
+		}
+	},
+
+	patterns: {
+		larvaPatternsDir: path.resolve( './node_modules/@penskemediacorp/larva-patterns' ),
+		projectPatternsDir: path.resolve( './src/patterns' ),
+	},
+
+	assets: {
+		path: ( () => {
+
+			// Fragile way to detect existing Larva sites
+			if ( fs.existsSync( path.resolve( './build/css' ) ) ) {
+				return path.resolve( './' );
+			}
+
+			return path.resolve( './node_modules/@penskemediacorp/larva' );
+		})(),
+	},
+
+	themeAssets: {},
+};
+
+module.exports = function getAppConfiguration( key, usePackageDefault = true ) {
+
+	try {
+
+		let appRoot = process.cwd();
+
+		if ( 'test' === process.env.NODE_ENV ) {
+			appRoot = path.join( __dirname, '../../__tests__/fixtures/' );
+		}
+
+		let config = require( `${appRoot}/larva.config.js` );
+
+		// If config not found in approot, fallback to package default in root
+		if ( undefined === config[key] && usePackageDefault ) {
+			return defaultConfig[ key ];
+		}
+
+		return config[key];
+
+	} catch ( error ) {
+		console.warn( 'Using default configuration. ');
+
+		return defaultConfig[ key ];
+	}
+};

package/lib/utils/getArgsFromCli.js

@@ -0,0 +1,3 @@
+module.exports = function getArgsFromCli() {
+	return process.argv.slice(2);
+}

package/lib/utils/getModuleNamesFromDirectory.js

@@ -0,0 +1,11 @@
+const getSubDirectoryNames = require( './getSubDirectoryNames' );
+const path = require( 'path' );
+
+module.exports = function getModuleNamesFromDirectory( directory, ignoredModules = [] ) {
+	let moduleNames = getSubDirectoryNames( path.join( directory , 'modules' ) );
+
+	return moduleNames.filter( ( moduleName ) => {
+		return ! moduleName.startsWith( '_' ) && -1 === ignoredModules.indexOf( moduleName );
+	});
+
+}

package/lib/utils/getPatternData.js

@@ -0,0 +1,34 @@
+const chalk = require( 'chalk' );
+const path = require( 'path' );
+/**
+ * Get Pattern Data
+ *
+ * @param {string} patternsPath
+ * @param {object} params Object containing name of pattern
+ */
+function getPatternData( patternsPath, params ) {
+
+	const variant = params.variant || 'prototype';
+	const patternPath = path.join( patternsPath, params.type, params.name, params.name + '.' + variant + '.js' );
+	const jsonPath = path.join( patternsPath, params.type, params.name, params.name + '.json' )
+
+	try {
+		return require( patternPath );
+	} catch( e ) {
+		const originalError = e;
+
+		try {
+			// Backwards compat for Deadline when patterns were stored as JSON
+			let patternData = require( jsonPath );
+			return patternData;
+		} catch ( e ) {
+			return {
+				message: `Error getting data for "${params.name}".<br>There is likely a problem with ${params.name}.${variant}.js.`,
+				error: originalError
+			}
+		}
+	}
+
+}
+
+module.exports = getPatternData;

package/lib/utils/getPatternPathsToLoad.js

@@ -0,0 +1,20 @@
+const fs = require( 'fs' );
+
+module.exports = function getPatternPathsToLoad( config ) {
+	let paths = [];
+
+	if ( undefined === config ) {
+		throw new Error( `Pattern configuration is undefined.` );
+	};
+
+	// Look in projectPatternsDir first.
+	if( fs.existsSync( config.projectPatternsDir ) ) {
+		paths.push( config.projectPatternsDir );
+	}
+
+	if( fs.existsSync( config.larvaPatternsDir ) ) {
+		paths.push( config.larvaPatternsDir );
+	}
+
+	return paths;
+}