@penskemediacorp/larva 1.2.1-alpha.0 → 1.3.0

package/scripts/config/gulpfile.js

@@ -0,0 +1,191 @@
+const gulp = require( 'gulp' );
+const gulpClean = require( 'gulp-clean' );
+const gulpIf = require( 'gulp-if' );
+const gulpIgnore = require( 'gulp-ignore' );
+const gulpPostCss = require( 'gulp-postcss' );
+const gulpRename = require( 'gulp-rename' );
+const gulpStylelint = require( 'gulp-stylelint' );
+
+const Fibers = require( 'fibers' );
+const globImporter = require( 'node-sass-glob-importer' );
+const { mkdirpSync } = require( 'fs-extra' );
+const path = require( 'path' );
+const postCss = require( 'postcss' );
+const sass = require( 'gulp-sass' );
+
+const stylelintConfig = require( './stylelint.config' );
+
+/**************
+Config
+**************/
+
+const cssDest = './build/css/';
+
+sass.compiler = require( 'sass' );
+
+const sassOpts = {
+	fiber: Fibers,
+	includePaths: [
+		path.resolve( './node_modules' ),
+		path.resolve( './src/scss' ),
+	],
+	importer: globImporter(),
+};
+
+const stylelintOpts = {
+	failAfterError: false,
+	config: stylelintConfig,
+	reporters: [
+		{
+			formatter: 'string',
+			console: true,
+		},
+	],
+};
+
+/**************
+Functions
+**************/
+
+/**
+ * Build CSS.
+ *
+ * Used for both prod and dev commands.
+ *
+ * Consider updating the name 'minify' to 'post' if/when
+ * more Post CSS functionality is added.
+ *
+ * @param {Function} done                      Post-build callback.
+ * @param {boolean}  minify                    Run post CSS and minify output.
+ * @param {boolean}  generateImportantVariants Whether to build variations with
+ *                                             `!important` added to all rules.
+ */
+const buildScss = (
+	done,
+	minify = false,
+	generateImportantVariants = false
+) => {
+
+	if ( minify ) {
+		sassOpts.outputStyle = 'compressed';
+	}
+
+	gulp.src( './entries/*.scss' )
+		.pipe( gulpStylelint( stylelintOpts ) )
+		.pipe( sass( sassOpts ).on( 'error', sass.logError ) )
+		.pipe( gulp.dest( cssDest ) )
+		.pipe( gulpIgnore.exclude( 'larva-ui.css' ) )
+		.pipe(
+			gulpIf(
+				generateImportantVariants,
+				gulpPostCss( [ declareImportanceForAll ] )
+			)
+		)
+		.pipe(
+			gulpIf(
+				generateImportantVariants,
+				gulpRename( { suffix: '-important' } )
+			)
+		)
+		.pipe( gulpIf( generateImportantVariants, gulp.dest( cssDest ) ) );
+
+	done();
+};
+
+/**
+ * Prepare destination directory.
+ *
+ * @param {Function} done Function called upon completion.
+ */
+const clean = ( done ) => {
+	gulp.src( cssDest, { read: false } ).pipe( gulpClean() );
+
+	mkdirpSync( cssDest );
+	done();
+};
+
+/**
+ * Build a task from dynamic input.
+ *
+ * @param {Function} done                      Function called upon completion.
+ * @param {boolean}  generateImportantVariants Whether to build variations with
+ *                                             `!important` added to all rules.
+ */
+const composeTask = ( done, generateImportantVariants = false ) => {
+	clean( () => {
+		stylelint( './src/**/*.scss' );
+		buildScss( done, true, generateImportantVariants );
+	} );
+};
+
+/**
+ * Add `!important` declarations to all rules, for use with older themes that
+ * have high specificity.
+ *
+ * Adapted from the `postcss-importantly` npm package, updated to work with
+ * latest version of PostCSS.
+ *
+ * @param {Object} style  PostCSS Root object for current CSS.
+ * @param {Object} result PostCSS Result object containing transformed CSS.
+ * @return {Result} PostCSS Result object.
+ */
+const declareImportanceForAll = ( style, result ) => {
+	const root = postCss.parse( style );
+
+	root.walkRules( ( rule ) => {
+		if ( 'atrule' === rule.parent.type && 'media' !== rule.parent.name ) {
+			return;
+		}
+
+		return rule.each( ( decl ) => {
+			if ( ! decl.value || decl.important ) {
+				return;
+			}
+
+			decl.value += '!important';
+
+			return decl;
+		} );
+	} );
+
+	result.root = root;
+
+	return result;
+};
+
+/**
+ * Run stylelint.
+ *
+ * @param {string} file Filename or glob to process.
+ */
+const stylelint = ( file ) => {
+	gulp.src( file ).pipe( gulpStylelint( stylelintOpts ) );
+};
+
+/**************
+Tasks
+***************/
+
+// Watch the changed file, compile and lint when changed.
+exports[ 'dev-scss' ] = () => {
+	gulp.watch( [ './src/**/*.scss', './entries/*.scss' ], buildScss ).on(
+		'change',
+		function ( file ) {
+			stylelint( file );
+		}
+	);
+};
+
+// Quickly build SCSS.
+exports[ 'build-scss' ] = ( done ) => {
+	buildScss( done );
+};
+
+// Run PostCSS on CSS.
+exports[ 'prod-scss' ] = ( done ) => {
+	composeTask( done );
+};
+
+exports[ 'prod-scss-with-important-variants' ] = ( done ) => {
+	composeTask( done, true );
+};

package/scripts/config/stylelint.config.js

@@ -0,0 +1,5 @@
+const rules = {
+	'extends': '@penskemediacorp/stylelint-config'
+};
+
+module.exports = rules;

package/scripts/config/svgo-config.json

@@ -0,0 +1,67 @@
+{
+	"plugins": [{
+			"removeTitle": false
+		},
+		{
+			"removeDoctype": true
+		},
+		{
+			"removeXMLNS": true
+		},
+		{
+			"removeXMLProcInst": true
+		},
+		{
+			"removeComments": true
+		},
+		{
+			"removeUselessDefs": true
+		},
+		{
+			"removeEmptyAttrs": true
+		},
+		{
+			"removeUselessStrokeAndFill": true
+		},
+		{
+			"removeUnknownsAndDefaults": true
+		},
+		{
+			"convertPathData": false
+		},
+		{
+			"cleanupIDs": true
+		},
+		{
+			"cleanupNumericValues": {
+				"floatPrecision": 3,
+				"leadingZero": true
+			}
+		},
+		{
+			"minifyStyles": true
+		},
+		{
+			"convertTransform": true
+		},
+		{
+			"cleanupAttrs": true
+		},
+		{
+			"convertPathData": true
+		},
+		{
+			"convertShapeToPath": true
+		},
+		{
+			"convertColors": {
+				"shorthex": false
+			}
+		},
+		{
+			"removeAttrs": {
+				"attrs": "fill"
+			}
+		}
+	]
+}

package/scripts/config/webpack.config.js

@@ -0,0 +1,95 @@
+const path = require( 'path' );
+const ESLintPlugin = require('eslint-webpack-plugin');
+
+const getConfig = require( '../../index' ).getConfig;
+
+const SRC_DIR = path.resolve( './entries' );
+const BUILD_DIR = path.resolve( './build/js' );
+
+const entries = getConfig( 'webpack' ).entries;
+
+const aliases = {
+	'@larva-js': path.resolve( './node_modules/@penskemediacorp/larva-js/src' ),
+	'@npm': path.resolve( './node_modules/' ),
+	... getConfig( 'webpack' ).aliases
+};
+
+const eslintConfig = getConfig( 'eslint', true );
+const eslintConfigFile = undefined !== eslintConfig ? eslintConfig.configFile : null;
+
+// Tools
+const { CleanWebpackPlugin } = require( 'clean-webpack-plugin' );
+
+
+//=========================================================
+//  Rules
+//---------------------------------------------------------
+const rules = {
+
+	/**
+	 * JS Loaders
+	 */
+	pre: {
+		enforce: 'pre',
+		test: /\.js$/,
+		exclude: /(node_modules|nobundle|vendor)/,
+	},
+	js: {
+		test: /\.js$/,
+		include: SRC_DIR,
+		exclude: /(node_modules|nobundle|vendor)/,
+		loader: 'babel-loader',
+		query: {
+			presets: [ '@babel/preset-env' ]
+		}
+	}
+};
+
+const plugins = {
+	cleanup: new CleanWebpackPlugin(),
+	eslint: new ESLintPlugin({
+		overrideConfigFile: eslintConfigFile
+	})
+};
+
+//=========================================================
+//  CONFIG
+//---------------------------------------------------------
+const config = {
+	entry: entries,
+	output: {
+		path: BUILD_DIR,
+		filename: '[name].js'
+	},
+	module: {
+		rules: [ rules.js ]
+	},
+	watch: false,
+	watchOptions: {
+		ignored: /node_modules/
+	},
+	resolve: {
+		alias: aliases
+	},
+	optimization: {
+		minimize: true
+	}
+};
+
+module.exports = ( env, argv ) => {
+
+	if ( 'development' === argv.mode ) {
+		config.devtool = 'source-map';
+		config.module.rules = ( config.module.rules || [] ).concat( [ rules.pre ] );
+		config.plugins = [ plugins.eslint ];
+	}
+
+	if ( 'production' === argv.mode ) {
+		console.log( 'Building Prod JS..' );
+
+		config.module.rules = ( config.module.rules || [] ).concat( [ rules.pre ] );
+		config.plugins = [ plugins.eslint, plugins.cleanup ];
+	}
+
+	return config;
+};

package/scripts/dev-js.js

@@ -0,0 +1,13 @@
+const path = require( 'path' );
+
+const spawnScript = require( '../lib/utils/spawnScript' );
+
+const configPath = path.join( __dirname, './config/webpack.config.js' );
+
+const args = [
+	`--config=${ configPath }`,
+	'--mode=development',
+	'--watch=true'
+];
+
+spawnScript( './node_modules/.bin/webpack', args );

package/scripts/dev-scss.js

@@ -0,0 +1,20 @@
+const spawn = require( 'cross-spawn' );
+const path = require( 'path' );
+
+const getArgsFromCli = require( '../lib/utils/getArgsFromCli' );
+
+const cliArgs = getArgsFromCli();
+const gulpfilePath = path.join( __dirname, './config/gulpfile.js' );
+
+// TODO: allow local gulpfile override by checking for --cwd and --gulpfile in cliArgs
+
+spawn.sync(
+	'./node_modules/.bin/gulp',
+	[
+		'--gulpfile',
+		gulpfilePath,
+		'--cwd',
+		process.cwd(),
+		... cliArgs
+	], { stdio: 'inherit' }
+);

package/scripts/help.js

@@ -0,0 +1,65 @@
+/**
+ * Help command for Larva.
+ *
+ * ## OPTIONS
+ *
+ * [<command>]
+ * : Slug of a command to display the CLI usage information.
+ *
+ * ## EXAMPLES
+ *
+ *     # Display a list of available commands.
+ *     $ npx @penskemediacorp/larva help
+ *
+ *     # Display the prod command docblock.
+ *     $ npx @penskemediacorp/larva help prod
+ */
+
+// Dependencies.
+const fs = require('fs');
+const path = require( 'path' );
+const shell = require( 'shelljs' );
+
+// CLI arguments.
+const getArgsFromCli = require( '../lib/utils/getArgsFromCli' );
+const cliArgs = getArgsFromCli();
+
+const allowedCommands = [
+	'help',
+	'link-all',
+	'lint',
+	'prod',
+	'start',
+	'upgrade',
+];
+
+// Display a generic help description.
+if ( 2 !== cliArgs.length ) {
+	console.log( 'Usage: npx @penskemediacorp/larval <command> [--help]\n' );
+	console.log( `Where <command> is one of ${allowedCommands.join( ', ' )}.\n` );
+	return;
+}
+
+// Check for invalid commands.
+const command = cliArgs[1];
+if ( ! allowedCommands.includes( command ) ) {
+	console.log( `Invalid command '${command}'.\n` );
+	return;
+}
+
+// Display the docblock for a given command.
+const pathToFile = path.resolve( __dirname, `${command}.js` );
+try {
+	if ( fs.existsSync( pathToFile ) ) {
+		fs.readFile( pathToFile, 'utf8', ( error, data ) => {
+			if ( error ) {
+				console.error( error );
+				return;
+			}
+			const fileParts = data.split( '*/', 1 );
+			console.log( fileParts[0] + '*/' );
+		} );
+	}
+} catch( error ) {
+	console.error( error );
+}

package/scripts/init.js

@@ -0,0 +1,21 @@
+const path = require( 'path' );
+const chalk = require( 'chalk' );
+const { copySync } = require( 'fs-extra' );
+
+const copyFrom = path.join( __dirname, 'larva' );
+const copyTo = process.cwd();
+
+copySync( copyFrom, copyTo );
+
+console.log(
+	chalk.green( 'Copied folder structure. Now, add the following scripts to package.json:' )
+);
+
+console.log( `
+"backstop": "backstop --config=node_modules/@penskemediacorp/backstopjs-config",
+"build-html": "larva build-html",
+"larva": "larva server --watch src -e twig,js,html",
+"parser": "./node_modules/.bin/twig-to-php-parser",
+"update-larva": "npm install @penskemediacorp/larva@latest",
+"write-json": "larva write-json"
+` );

package/scripts/larva/.nvmrc

@@ -0,0 +1 @@
+14

package/scripts/larva/README.md

@@ -0,0 +1,29 @@
+# IMPORTANT!!!!
+
+After this directory has been copied into a consuming project, [follow these steps](https://confluence.pmcdev.io/x/JQqeAw), delete this section of the readme, and replace the {Project} text below with the name of the brand (in the bright future, this will be automated).
+
+# {Project} Larva
+
+This is configuration only instance of Larva. There should be no CSS or JS compiled here, only JSON configuration using existing styles from larva.css. If additional styles are needed, they should be [contributed upstream to the Larva packages](https://confluence.pmcdev.io/x/EQNCB).
+
+## Links
+
+* [{Project} design tokens]().
+* [{Project} style guide on Invision or XD]().
+* [{Project} style guide on the static site]().
+
+## Development
+
+To start developing:
+
+1. Run `npm install` from theme-directory/assets.
+2. Run `npm run larva` to open the Larva server.
+
+Add pattern configurations by creating variants for modules.
+
+## Larva Commands
+
+* `npm run larva` - Start the Larva pattern server. Navigate in the browser to http://localhost:3000.
+* `npm run parser` - Parse recently changed pattern Twig files to PHP.
+* `npm run write-json` - write pattern objects to JSON files.
+

package/scripts/larva/larva.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+	brand: ''
+};

package/scripts/larva/src/patterns/README.md

@@ -0,0 +1,3 @@
+These are project-level patterns. You can build new UI here, or configure existing UI from Larva shared modules.
+
+Read more about using patterns on the [Larva Wiki](https://github.com/penske-media-corp/pmc-larva/wiki/).

package/scripts/larva/src/patterns/base.html

@@ -0,0 +1,6 @@
+{% extends "@larva/base.html" %}
+
+{% block stylesheets %}
+	{# Add references to theme stylesheets here #}
+{% endblock %}
+

package/scripts/larva/src/patterns/components/README.md

@@ -0,0 +1,3 @@
+These are project-level *components*. You should only have a few at most in here.
+
+Read more about using patterns on the [Larva Wiki](https://github.com/penske-media-corp/pmc-larva/wiki/).

package/scripts/larva/src/patterns/modules/README.md

@@ -0,0 +1,3 @@
+These are project-level *modules*. You will have lots and lots of modules!
+
+Read more about using shared modules on the [Larva Wiki](https://github.com/penske-media-corp/pmc-larva/wiki/).

package/scripts/larva/src/patterns/objects/README.md

@@ -0,0 +1,3 @@
+These are project-level *objects*. You should only have a few at most in here.
+
+Read more about using patterns on the [Larva Wiki](https://github.com/penske-media-corp/pmc-larva/wiki/).

package/scripts/larva/src/patterns/one-offs/README.md

@@ -0,0 +1,3 @@
+These are project-level *one-offs*.
+
+One-offs are technical debt and marked as such.

package/scripts/link-all.js

@@ -0,0 +1,40 @@
+/**
+ * This command can be used from within any Larva project to link the Larva
+ * packages (from the monorepo) for local development.
+ *
+ * @see https://github.com/penske-media-corp/pmc-larva/blob/master/README.md#linking-larva-for-local-development
+ *
+ * ## OPTIONS
+ *
+ * [--help]
+ * : Display usage and examples for this command.
+ *
+ * ## EXAMPLES
+ *
+ *     # NPM link local packages to Larva monorepo.
+ *     $ npx @penskemediacorp/larva link-all
+ *
+ *     # Help command.
+ *     $ npx @penskemediacorp/larva link-all help
+ */
+
+const shell = require( 'shelljs' );
+
+// CLI arguments.
+const getArgsFromCli = require( '../lib/utils/getArgsFromCli' );
+const cliArgs = getArgsFromCli();
+
+// Handle help command.
+if ( cliArgs.includes( '--help' ) ) {
+    shell.exec( `npx @penskemediacorp/larva help link-all` );
+    return;
+}
+
+shell.exec( 'npm link @penskemediacorp/larva' );
+shell.exec( 'npm link @penskemediacorp/larva-css' );
+shell.exec( 'npm link @penskemediacorp/larva-js' );
+shell.exec( 'npm link @penskemediacorp/larva-patterns' );
+shell.exec( 'npm link @penskemediacorp/larva-scss' );
+shell.exec( 'npm link @penskemediacorp/larva-svg' );
+shell.exec( 'npm link @penskemediacorp/larva-tokens' );
+shell.exec( 'npm link @penskemediacorp/twig-to-php-parser' );

package/scripts/lint-js.js

@@ -0,0 +1,11 @@
+const getAppConfiguration = require( '../lib/utils/getAppConfiguration' );
+const spawnScript = require( '../lib/utils/spawnScript' );
+
+const { configFile } = getAppConfiguration( 'eslint' );
+
+const args = [
+	'--c',
+	configFile
+];
+
+spawnScript( './node_modules/.bin/eslint', args );

package/scripts/lint-scss.js

@@ -0,0 +1,13 @@
+const path = require( 'path' );
+
+const stylelintConfigPath = path.join( __dirname, './config/stylelint.config.js' );
+const spawnScript = require( '../lib/utils/spawnScript' );
+
+const args = [
+	'files',
+	'./src/scss',
+	'--config',
+	stylelintConfigPath
+];
+
+spawnScript( './node_modules/.bin/stylelint', args );

package/scripts/lint.js

@@ -0,0 +1,73 @@
+/**
+ * Lint JavaScript and CSS files in a Larva project.
+ *
+ * ## OPTIONS
+ *
+ * [--help]
+ * : Display usage and examples for this command.
+ *
+ * [--css]
+ * : Lint CSS assets.
+ *
+ * [--js]
+ * : Lint JavaScript assets.
+ *
+ * [--fix]
+ * : Try to automatically fix any issues that arise while linting.
+ *
+ * ## EXAMPLES
+ *
+ *     # Lint CSS and JavaScript assets.
+ *     $ npx @penskemediacorp/larva lint
+ *
+ *     # Only lint CSS assets.
+ *     $ npx @penskemediacorp/larva lint --css
+ *
+ *     # Only lint JavaScripot assets.
+ *     $ npx @penskemediacorp/larva lint --js
+ *
+ *     # Fix CSS and JavaScript assets.
+ *     $ npx @penskemediacorp/larva lint --fix
+ *
+ *     # Mix and match, fix JavaScript assets.
+ *     $ npx @penskemediacorp/larva lint --js --fix
+ *
+ *     # Help command.
+ *     $ npx @penskemediacorp/larva lint --help
+ */
+
+// Dependencies.
+const path = require( 'path' );
+const shell = require( 'shelljs' );
+
+// Construct some paths to point our scripts at.
+const binPath = path.resolve( __dirname, '../bin/larva.js' ); // For sibling scripts.
+const workingDirectory = process.cwd(); // For paths relative to the directory this script was called from.
+
+// CLI arguments.
+const getArgsFromCli = require( '../lib/utils/getArgsFromCli' );
+const cliArgs = getArgsFromCli();
+
+// Handle help command.
+if ( cliArgs.includes( '--help' ) ) {
+    shell.exec( `npx @penskemediacorp/larva help lint` );
+    return;
+}
+
+// Trigger linting when a specific flag is present, or when neither flag is
+// present.
+const lintCSS = cliArgs.includes( '--css' ) || ! cliArgs.includes( '--js' );
+const lintJS = cliArgs.includes( '--js' ) || ! cliArgs.includes( '--css' );
+
+// Appends ` fix` to our linting scripts if the flag is present.
+const fix = cliArgs.includes( '--fix' ) ? ' fix' : '';
+
+if ( lintCSS ) {
+	console.log( 'Linting CSS assets\n\n\n' );
+	shell.exec( `${binPath} lint-scss${fix}` );
+}
+
+if ( lintJS ) {
+	console.log( 'Linting JavaScript assets\n\n\n' );
+	shell.exec( `${binPath} lint-js ${workingDirectory}${fix}` );
+}