@penskemediacorp/larva 1.5.6-alpha.0 → 1.6.1

package/.eslintignore

@@ -0,0 +1,6 @@
+lib/**/*.js
+node_modules/**/*.js
+lib/**/*.js
+__tests__/**/*.js
+build/**/*.js
+src/js/vendor/*.js

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Penske Media Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,67 +1,126 @@
-# Larva!
+# Larva
 
-If you want _all of Larva_, this is your repo. This is where you should start for new projects and for refactoring old projects onto the system.
+_Note:_ This package may eventually be split into separate packages.
 
-This package is essentially a wrapper that brings all of the other packages together, and provides the tools for using them to develop modules. It contains an Express server and UI for configuring patterns, and _will_ contain scripts to scaffold patterns, test them, and probably do all kinds of other cools stuff. For the time being, it's pretty much just the server and a very basic UI.
+By nature it is a wrapper package that brings all of the smaller Larva packages together, and provides a sandbox for testing Larva tools. Now, it also contains the `larva` binary build scripts and the Larva UI Express server for patterns development.
+
+* An Express server and UI for building project-level patterns and configuring existing patterns
+* Gulp configuration for building SCSS
+* A basic webpack configuration for JS
+* An init command for scaffolding the Larva directory structure
+* The `write-json` script for building the JSON for each pattern
+* A `larva` binary that provides access to all of the above
 
 ## Usage
 
-### Absolutely required directory structure
+### If a brand new project:
+
+In order to avoid conflicting node versions, Larva should be contained to its own directory.
+
+**If you are working in a brand new project**, create a directory called `assets` and follow the below steps from the root of `assets`.
+
+**If you are working in an existing project**, create a directory called `larva` and follow the below steps from its root.
+
+First we will initialize an npm package, install Larva, and run the init command to scaffold our directory structure:
+
+_// TODO: the `npx` workflow needs to be tested once this is released on npm._
+
+```
+# Create an npm package
+$ npm init
+
+# Add Larva and scaffold directory structure
+$ npx @penskemediacorp/larva init
+```
 
-Any project consuming Larva, must have the following directory structure:
+This will install the main Larva package and create a directory called larva/ that contains a scaffold of the directory structure. Move the contents of this directory into your current working directory so that the directory structure aligns with the following:
 
 ```
 |- pmc-consuming-project/
-	|- assets/
+	|- assets/ (or larva if in an older code-base)
 		|- build/
-			|- css/
-			|- js/
-			|- images/
 		|- node_modules/
 		|- src/
-			|- patterns/
-				|- 04-components/
-				|- 05-objects/
-				|- 06-algorithms/
-				|- 07-utilities/
-				|- 08-modules/
-				|- 09-one-offs/
-		|- public
-			|- {fonts}
+		|- entries/
+		|- public/
 		|- package.json
 		|- larva.config.js
-	|- template-parts/ (only if there are parsed patterns)
-		|- patterns/
+		|- .nvmrc
 ```
-### In a brand new project
 
-To install Larva, run the following command from the asset directory of a consuming project:
+Next, check in root README.md from the scaffold and copy the scripts into package.json as directed.
+
+Finally, create a directory `template-parts/patterns` to hold the PHP version of patterns. If working from the CLI, you can copy/paste this bash command:
+
 ```
-npm install @penskemediacorp/larva
+|- pmc-consuming-project/
+	|- template-parts/
+		|- patterns/
 ```
 
-Then, create a file, larva.config.js in the assets directory. Add the following:
+## `larva` Binary & Build Scripts
 
-```
-const path = require( 'path' );
+Inspired by [@wordpress/scripts](https://github.com/WordPress/gutenberg/tree/master/packages/scripts), this package provides a bindary and several scripts for performing common tasks when building UI with Larva. This code lives in the `scripts` directory of this package.
+
+For asset building commands, JS and SCSS can be run at the same time, or separately, in order to minimize the build time for cases where either JS or SCSS, not both, need to be built.
+
+### Usage
 
-module.exports = {
-	patterns: {
-		larvaPatternsDir: path.resolve( __dirname, 'node_modules/@penksemediacorp/larva-patterns' ),
-		projectPatternsDir: path.resolve( __dirname, './src/patterns' )
+Assuming Larva is installed, make sure the @penskemediacorp/larva package is at least at version 8.0.0-alpha.
+
+To use the build scripts, add the following to package.json in a project that uses the [Larva assets directory structure](https://github.com/penske-media-corp/pmc-larva/tree/master/packages/larva#usage):
+
+```
+{
+	"scripts": {
+		"prod": "larva prod-scss & larva prod-js",
+		"prod:scss": "larva prod-scss",
+		"prod:js": "larva prod-js",
+		"dev": "larva dev-js & larva dev-scss",
+		"dev:scss": "larva dev-scss",
+		"dev:js": "larva dev-js",
+		"lint": "larva lint-scss & larva lint-js",
+		"lint:scss": "larva lint-scss",
+		"lint:js": "larva lint-js ./",
+		"lint-fix": "larva lint-scss --fix & npm run lint:js --fix",
+		"lint-fix:scss": "larva lint-scss --fix",
+		"lint-fix:js": "larva lint-js --fix",
+		"larva": "larva server",
+		"write-json": "larva write-json larva && larva write-json",
+		"build-icons": "larva build-icons",
+		"build-html": "larva build-html"
 	}
 }
 ```
 
-Create the following directories in your-theme/assets/src/patterns: 
+#### Script Usage Notes
 
+**`build-html`**
 
-(yes, there will be a scaffold task, someday)
+This is the script for building static HTML files for deployment. It accepts two CLI arguments, the first for build source ('project' or 'larva') and the second as an optional port number. The default is 3000.
 
-To start the server, you must be in the same directory as `larva.config.js` or, in other words, working within a "host" project. The Larva mono-repo is set up to be a "host" project, and the server can be started from within the root of the repository with the following command:
+Example of building HTML for project Larva patterns:
+`npm run build-html -- project`.
 
-```
-➜ pmc-larva$ npm run larva
-```
+Example of building HTML for Larva patterns with a server on port 2003:
+`npm run build-html -- larva 2003`.
+
+**`prod:scss`**
+
+This command accepts an optional flag, `--generate-important-variants`, which
+produces a second version of each entrypoint. In these variants, every rule
+includes the `!important` declaration. These stylesheets are used with themes
+that have not fully adopted Larva, allowing Larva to overcome the theme's
+styles' specificity.  
+
+### Overview of Functionality
+
+This operates by way of a single binary, `larva`, and provides a layer of abstraction around CLI commands from various tools. The `larva` binary will point to a default configuration for each command and run its package's associated binary (e.g. `eslint` or `gulp`). The configurations are stored in separate package so as to be available to projects not using Larva.
+
+For example, when the below scripts are present in a consuming projects package.json, the following would happen for `npm run dev:scss` (with the `scripts` value: `larva dev-scss`) in this package:
+1. In `bin/larva.js`, get arguments from CLI, and execute a file with name corresponding to the argument.
+2. `dev-scss.js` executes `gulp` CLI with additional arguments defined in the JS file via `spawnScript`, which uses the `cross-spawn` npm package to handle cross-platform inconsistencies.
 
-This will bring up the server for developing patterns at localhost:3000.
+Similarly, `npm run lint:js` (with the `scripts` value: `larva lint-js`) would do the following:
+1. In `bin/larva.js`, get arguments from CLI and execute lint-js.js.
+2. `lint-js.js` executes the `eslint` CLI with both CLI arguments and specific arguments defined in the script.

package/__tests__/fixtures/build/css/common.inline.css

@@ -1,2 +1 @@
-.pmc-a-wrapper {
-  margin: auto; }
+.testing { color: green; }

package/__tests__/fixtures/build/js/larva-ui.js

@@ -0,0 +1 @@
+console.log( 'test js build file' );

package/__tests__/fixtures/build/svg/defs/sprite.svg

@@ -0,0 +1 @@
+<svg></svg>

package/__tests__/fixtures/larva.config.js

@@ -12,23 +12,32 @@ module.exports = {
 	},
 
 	backstop: {
-		pmcMainQaUrl: 'https://pmc:for-the-win@deadline-2019.pmcqa.com',
-		pmcTestPaths: [
+		testBaseUrl: 'https://pmc:for-the-win@deadline-2019.pmcqa.com',
+		testPaths: [
 			'/',
 			'/blog/'
 		],
-		pmcScenario: {
+		testScenario: {
 			'delay': 5000,
 			'misMatchThreshold': 0.5
-		}
+		},
+		larvaModules: [ 'footer', 'mega-menu-content', 'social-share' ]
+	},
+
+	patterns: {
+		projectPatternsDir: path.join( __dirname, './src/patterns' ),
+		larvaPatternsDir: path.resolve( __dirname, '../../../larva-patterns' ),
+		ignoredModules: [
+			'ignore-me'
+		]
+	},
+
+	assets: {
+		path: __dirname
 	},
 
 	parser: {
 		isCore: false,
 	},
-	
-	patterns: {
-		themePatternsDir: path.resolve( './src/patterns' ),
-		larvaPatternsDir: path.resolve( __dirname, '../../node_modules/@penskemediacorp/larva-patterns' )
-	}
+
 };

package/__tests__/fixtures/public/some-library.js

@@ -0,0 +1 @@
+console.log( 'test' );

package/__tests__/fixtures/src/patterns/components/c-nav-link/c-nav-link.featured.aia.js

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

package/__tests__/fixtures/src/patterns/components/c-nav-link/c-nav-link.featured.js

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

package/__tests__/fixtures/src/patterns/components/c-nav-link/c-nav-link.js

@@ -0,0 +1 @@
+// this could be JSX or a React component.

package/__tests__/fixtures/src/patterns/components/c-nav-link/c-nav-link.prototype.js

@@ -1,3 +1,3 @@
 module.exports = {
-	"modifier_class": ""
+	modifier_class: ''
 };

package/__tests__/fixtures/src/patterns/components/c-tagline/c-tagline.prototype.js

@@ -0,0 +1,3 @@
+module.exports = {
+	c_tagline_text: 'overrode the larva pattern'
+}

package/__tests__/fixtures/src/patterns/modules/_also-ignored/_also-ignored.prototype.js

@@ -0,0 +1,3 @@
+module.exports = {
+	also_ignored_classes: 'lrv-u-color-black'
+};

package/__tests__/fixtures/src/patterns/modules/_also-ignored/_also-ignored.twig

@@ -0,0 +1,3 @@
+<div class="_also-ignored {{ _also_ignored_classes }}">
+
+</div>

package/__tests__/fixtures/src/patterns/modules/test-module/test-module.featured.js

@@ -0,0 +1,3 @@
+module.exports = {
+	test_module_classes: 'lrv-a-glue'
+}

package/__tests__/fixtures/src/patterns/modules/test-module/test-module.prototype.js

@@ -0,0 +1,3 @@
+module.exports = {
+	test_module_classes: 'lrv-u-flex'
+}

package/__tests__/fixtures/src/patterns/one-offs/newswire/newswire.html

@@ -0,0 +1 @@
+<h1>Newsire</h1>

package/__tests__/fixtures/src/patterns/one-offs/newswire/newswire.prototype.js

@@ -0,0 +1,3 @@
+module.exports = {
+	name: "newswire"
+};

package/__tests__/lib/generateStatic.test.js

@@ -0,0 +1,140 @@
+const path = require( 'path' );
+const exec = require( 'child_process' ).exec;
+const app = require( '../../lib/server' );
+const fs = require( 'fs-extra' );
+
+const port = 5555;
+const urlBase = 'http://localhost:' + port + '/larva';
+const generateStatic = require( '../../lib/generateStatic' );
+
+const fixture = path.join( __dirname, '../fixtures' );
+const buildPath = path.join( fixture, './build/html/project' );
+
+beforeAll( ( done ) => {
+	app.listen( port, () => {
+		done();
+	});
+});
+
+describe( 'generateStatic', () => {
+
+	beforeEach( ( done ) => {
+
+		exec( 'mkdir -p ' + buildPath, ( err ) => {
+			if ( err ) {
+				console.error( err );
+			}
+			done();
+		} );
+
+	} );
+
+	it( 'creates an index.html file for a prototype pattern', ( done ) => {
+
+		const routesArr = [
+			'components/c-link'
+		];
+
+		generateStatic( routesArr, buildPath, () => {
+			expect(
+				fs.existsSync( path.join( buildPath, 'components/c-link/index.html' ) )
+			).toBe( true );
+			done();
+		}, urlBase );
+
+	} );
+
+	it( 'creates an html file for a pattern variant', ( done ) => {
+		const routesArr = [
+			'components/c-button/brand-basic'
+		];
+
+		generateStatic( routesArr, buildPath, () => {
+			expect(
+				fs.existsSync( path.join( buildPath, 'components/c-button/brand-basic/index.html' ) )
+			).toBe( true );
+			done();
+		}, urlBase );
+
+	} );
+
+	it( 'contains content for the pattern', ( done ) => {
+		const routesArr = [
+			'modules/footer',
+		];
+
+		generateStatic( routesArr, buildPath, () => {
+			expect(
+				// Hacky way to test that the response actually contains
+				// the content, not an error.
+				fs.readFileSync(
+					path.join( buildPath, routesArr[0] + '/index.html' ),
+					{ encoding: 'utf8' }
+				).indexOf( 'footer_classes' )
+			).not.toBe( -1 );
+			done();
+		}, urlBase );
+	} );
+
+	it( 'copies static assets', ( done ) => {
+		const routesArr = [
+			'components/c-button/brand-basic'
+		];
+
+		generateStatic( routesArr, buildPath, () => {
+
+			// This is kinda sloppy and may be annoying to maintain, and there is
+			// surely a more elegant way to test this functionality than checking
+			// if the file exists...
+
+			// JS
+			expect(
+				fs.existsSync( path.join( buildPath, '../assets/build/js/larva-ui.js' ) )
+			).toBe( true );
+
+			// CSS
+			expect(
+				fs.existsSync( path.join( buildPath, '../assets/build/css/common.inline.css' ) )
+			).toBe( true );
+
+			// Images
+			expect(
+				fs.existsSync( path.join( buildPath, '../assets/build/images/test.png' ) )
+			).toBe( true );
+
+			// SVG
+			expect(
+				fs.existsSync( path.join( buildPath, '../assets/build/svg/defs/sprite.svg' ) )
+			).toBe( true );
+
+			// Public dir
+			expect(
+				fs.existsSync( path.join( buildPath, '../assets/public/some-library.js' ) )
+			).toBe( true );
+
+			done();
+
+		}, urlBase );
+
+	} );
+
+	afterEach( ( done ) => {
+
+		const htmlDir = path.join( buildPath, '../' );
+
+		exec( 'rm -r ' + htmlDir, ( err ) => {
+			if ( err ) {
+				console.error( err );
+			}
+			done();
+		} );
+
+	} );
+
+} );
+
+afterAll( async ( done ) => {
+	const server = app.listen();
+	server.close();
+	done();
+});

package/__tests__/lib/utils/clonePatternData.test.js

@@ -1,19 +1,23 @@
-const assert = require( 'assert' );
 const path = require( 'path' );
-const fixture = path.join( __dirname, '../../fixtures' );
-
 const clonePatternData = require( '../../../lib/utils/clonePatternData' );
-const originalPatternData = require( fixture + '/src/patterns/04-components/c-nav-link/c-nav-link.prototype' );
+const getConfig = require( '../../../lib/utils/getAppConfiguration' );
+const { projectPatternsDir, larvaPatternsDir } = getConfig( 'patterns' );
 
 describe( 'clonePatternData', () => {
-	const clonedPatternData = clonePatternData( fixture + '/src/patterns/04-components/c-nav-link/c-nav-link.prototype' );
 
-	it( 'when cloned data is modified it does not affect the source object', () => {
-		clonedPatternData.modifier_class = "changed-class";
-		assert.notEqual( clonedPatternData.modifier_class, originalPatternData.modifier_class );
+	it( 'gets object from project patterns dir first', () => {
+
+		const expected = require( path.join( projectPatternsDir, '/components/c-tagline/c-tagline.prototype' ) );
+		const c_tagline = clonePatternData( 'components/c-tagline/c-tagline.prototype');
+
+		expect( c_tagline ).toStrictEqual( expected );
 	});
-	
-	it( 'contains default data provided by the initial object', () => {
-		assert.equal( clonedPatternData.o_nav_title_text, originalPatternData.o_nav_title_text );
+
+	it( 'falls back to object from larva patterns dir', () => {
+		const expected = require( path.join( larvaPatternsDir, '/components/c-button/c-button.prototype' ) );
+		const c_button = clonePatternData( 'components/c-button/c-button.prototype');
+
+		expect( c_button ).toStrictEqual( expected );
 	});
-});
+
+});

package/__tests__/lib/utils/getAllPatternsObj.test.js

@@ -0,0 +1,45 @@
+const path = require( 'path' );
+const getAppConfiguration = require( '../../../lib/utils/getAppConfiguration' );
+const getAllPatternsObj = require( '../../../lib/utils/getAllPatternsObj' );
+
+const expectedPatterns = {
+	'__tests__' : {},
+	'components': {
+		'c-nav-link': [
+			'featured.aia',
+			'featured',
+			'prototype'
+		],
+		'c-tagline': [
+			'prototype'
+		]
+	},
+	'modules': {
+		'test-module': [
+			'featured',
+			'prototype'
+		]
+	},
+	'objects': {
+		'o-crap': [],
+		'o-nav': []
+	},
+	'one-offs': {
+		'newswire': [
+			'prototype'
+		]
+	}
+}
+const config = getAppConfiguration( 'patterns' );
+
+describe( 'getAllPatternsObj', () => {
+
+	it( 'returns an object containing all patterns and variants', () => {
+
+		expect(
+			getAllPatternsObj( config.projectPatternsDir )
+		).toEqual(
+			expectedPatterns
+		);
+	});
+});

package/__tests__/lib/utils/getAppConfiguration.test.js

@@ -0,0 +1,13 @@
+const path = require( 'path' );
+const fixture = path.join( __dirname, '../../fixtures' );
+
+const getAppConfiguration = require( '../../../lib/utils/getAppConfiguration' );
+const expectedLarvaConfig = require( fixture + '/larva.config.js' );
+
+describe( 'getAppConfiguration', () => {
+
+	it( 'Get Larva Configuration', () => {
+		expect(getAppConfiguration( 'backstop' )).toStrictEqual( expectedLarvaConfig.backstop );
+	});
+
+});

package/__tests__/lib/utils/getModuleNamesFromDirectory.test.js

@@ -0,0 +1,23 @@
+const getModuleNamesFromDirectory = require( '../../../lib/utils/getModuleNamesFromDirectory' );
+const getAppConfiguration = require( '../../../lib/utils/getAppConfiguration' );
+
+const config = getAppConfiguration( 'patterns' );
+
+describe( 'getModuleNamesFromDirectory', () => {
+	it( 'gets an array of modules', () => {
+		expect( getModuleNamesFromDirectory( config.projectPatternsDir, config.ignoredModules ) ).toEqual( expect.arrayContaining( [ 'test-module' ] ) );
+	});
+
+	it( 'ignored modules with underscores', () => {
+		expect( getModuleNamesFromDirectory( config.projectPatternsDir, config.ignoredModules ) ).toEqual( expect.not.arrayContaining( [ '_also-ignored' ] ) );
+	});
+
+	it( 'ignores modules listed in larva.config.ignoredModules', () => {
+		expect( getModuleNamesFromDirectory( config.projectPatternsDir, config.ignoredModules ) ).toEqual( expect.not.arrayContaining( [ 'ignore-me' ] ) );
+	});
+
+	it( 'gets module names from larva', () => {
+		expect( getModuleNamesFromDirectory( config.larvaPatternsDir, config.ignoredModules ) ).toEqual( expect.arrayContaining( [ 'pmc-footer' ] ) );
+	});
+
+});

package/__tests__/lib/utils/getPatternData.test.js

@@ -7,21 +7,48 @@ const getPatternData = require( '../../../lib/utils/getPatternData' );
 const appConfiguration = require( '../../../lib/utils/getAppConfiguration' )('patterns');
 
 const expectedSchema = require( fixture + '/src/patterns/components/c-nav-link/c-nav-link.prototype.js' );
+const expectedVariantSchema = require( fixture + '/src/patterns/components/c-nav-link/c-nav-link.featured.js' );
 const expectedSchemaFromJson = require( fixture + '/src/patterns/objects/o-crap/o-crap.json' );
 const expectedPath = fixture + '/src/patterns/objects/o-nav/o-nav.json';
+const expectedOneOffSchema = require( fixture + '/src/patterns/one-offs/newswire/newswire.prototype.js' );
+
+let compStub = {
+	name: 'c-nav-link',
+	type: 'components',
+	variant: 'prototype'
+};
+
+const objStub = {
+	name: 'o-crap',
+	type: 'objects',
+	variant: 'prototype'
+};
+
+const oneOffStub = {
+	name: 'newswire',
+	type: 'one-offs',
+	variant: 'prototype'
+};
 
 describe( 'getPatternData', () => {
-	it( 'throws an error if no pattern prototype is found', () => {
-		assert.throws( () => getPatternData( fixture, { type: 'objects', name: 'o-nav' } ), Error );
+	
+	it( 'first returns the pattern object if the schema is found', () => {
+		assert.equal( getPatternData( fixture + '/src/patterns', compStub ), expectedSchema );
 	});
 
-	it( 'first returns the pattern object if the schema is found', () => {
-		assert.equal( getPatternData( fixture + '/src/patterns', { name: 'c-nav-link' } ), expectedSchema );
+	it( 'returns the pattern object for one-offs', () => {
+		assert.equal( getPatternData( fixture + '/src/patterns', oneOffStub ), expectedOneOffSchema );
 	});
 
 	it( 'returns the pattern json object if no prototype is found', () => {
-		assert.equal( getPatternData( fixture + '/src/patterns', { name: 'o-crap' } ), expectedSchemaFromJson );
+		assert.equal( getPatternData( fixture + '/src/patterns', objStub ), expectedSchemaFromJson );
 	});
+
+	it( 'gets a variant specified in params', () => {
+		compStub.variant = 'featured';
+		assert.equal( getPatternData( fixture + '/src/patterns', compStub ), expectedVariantSchema );
+	});
+
 });