@penskemediacorp/larva 1.0.2-alpha.0 → 1.1.0

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,11 +1,126 @@
-# `larva`
+# Larva
 
-> TODO: description
+_Note:_ This package may eventually be split into separate packages.
+
+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
 
+### 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._
+
 ```
-const larva = require('larva');
+# Create an npm package
+$ npm init
 
-// TODO: DEMONSTRATE API
+# Add Larva and scaffold directory structure
+$ npx @penskemediacorp/larva init
 ```
+
+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/ (or larva if in an older code-base)
+		|- build/
+		|- node_modules/
+		|- src/
+		|- entries/
+		|- public/
+		|- package.json
+		|- larva.config.js
+		|- .nvmrc
+```
+
+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:
+
+```
+|- pmc-consuming-project/
+	|- template-parts/
+		|- patterns/
+```
+
+## `larva` Binary & Build Scripts
+
+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
+
+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"
+	}
+}
+```
+
+#### Script Usage Notes
+
+**`build-html`**
+
+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.
+
+Example of building HTML for project Larva patterns:
+`npm run build-html -- project`.
+
+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.
+
+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

@@ -0,0 +1 @@
+.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

@@ -0,0 +1,43 @@
+const path = require( 'path' );
+
+module.exports = {
+
+	webpack: {
+		entry: {
+			common: './common.entry.js',
+			critical: './critical.entry.js',
+			special: './special.entry.js',
+			great: './great.entry.js'
+		}
+	},
+
+	backstop: {
+		testBaseUrl: 'https://pmc:for-the-win@deadline-2019.pmcqa.com',
+		testPaths: [
+			'/',
+			'/blog/'
+		],
+		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,
+	},
+
+};

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.json

@@ -0,0 +1,3 @@
+{
+	"modifier_class": "not expected"
+}

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

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

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

@@ -0,0 +1,3 @@
+<a class="c-nav-link {{ c_nav_link_classes }}" href="{{ c_nav_link_url }}">
+	{{ c_nav_link_text }}
+</a>

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/objects/o-crap/o-crap.json

@@ -0,0 +1,3 @@
+{
+	"o_crap_classes": "hello class here"
+}

package/__tests__/fixtures/src/patterns/objects/o-crap/o-crap.twig

@@ -0,0 +1 @@
+<p class="o-crap {{ modifier_class }} {{ o_crap_classes }}">{{ o_crap_text }}</p>

package/__tests__/fixtures/src/patterns/objects/o-nav/o-nav.twig

@@ -0,0 +1,14 @@
+<nav class="o-nav {{ modifier_class }} {{ o_nav_classes }}" data-dropdown="{{ o_nav_data_attributes }}">
+
+	{% if o_nav_title_text %}
+		<h4 class="o-nav__title {{ o_nav_title_classes }}" data-dropdown-list-item="{{ o_nav_title_data_attributes }}"> {{ o_nav_title_text }}</h4>
+	{% endif %}
+
+	<ul class="o-nav__list {{ o_nav_list_classes }}" data-dropdown-list="{{ o_nav_list_data_attributes }}">
+		{% for item in o_nav_list_items %}
+			<li class="o-nav__list-item {{ o_nav_list_item_classes }}" data-dropdown-list-item="{{ o_nav_list_item_data_attributes }}">
+				{% include "../../04-components/c-nav-link/c-nav-link.twig" with item %}
+			</li>
+		{% endfor %}
+	</ul>
+</nav>

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__/fixtures/template-parts/some-template.php

@@ -0,0 +1,3 @@
+<?php
+
+echo "hello";

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

@@ -0,0 +1,23 @@
+const path = require( 'path' );
+const clonePatternData = require( '../../../lib/utils/clonePatternData' );
+const getConfig = require( '../../../lib/utils/getAppConfiguration' );
+const { projectPatternsDir, larvaPatternsDir } = getConfig( 'patterns' );
+
+describe( 'clonePatternData', () => {
+
+	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( '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

@@ -0,0 +1,55 @@
+const assert = require( 'assert' );
+const path = require( 'path' );
+const fs = require( 'fs' );
+const fixture = path.join( __dirname, '../../fixtures' );
+
+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( 'first returns the pattern object if the schema is found', () => {
+		assert.equal( getPatternData( fixture + '/src/patterns', compStub ), 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', objStub ), expectedSchemaFromJson );
+	});
+
+	it( 'gets a variant specified in params', () => {
+		compStub.variant = 'featured';
+		assert.equal( getPatternData( fixture + '/src/patterns', compStub ), expectedVariantSchema );
+	});
+
+});
+
+
+

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

@@ -0,0 +1,13 @@
+const assert = require( 'assert' );
+const path = require( 'path' );
+const fixture = path.join( __dirname, '../../fixtures' );
+const getPatternPathsToLoad = require( '../../../lib/utils/getPatternPathsToLoad' );
+const appConfiguration = require( '../../../lib/utils/getAppConfiguration' )('patterns');
+
+describe( 'getPatternPathsToLoad', () => {
+
+	it( 'returns an array of paths loads larvaPath if it is the core theme', () => {
+		assert.equal( getPatternPathsToLoad( appConfiguration ).length, 2 );
+	});
+
+});