Add warning package

bin/api-docs/packages.js

@@ -32,6 +32,7 @@ const packages = [
 	'shortcode',
 	'url',
 	'viewport',
+	'warning',
 	'wordcount',
 ];
 

docs/manifest-devhub.json

@@ -1487,6 +1487,12 @@
 		"markdown_source": "../packages/viewport/README.md",
 		"parent": "packages"
 	},
+	{
+		"title": "@wordpress/warning",
+		"slug": "packages-warning",
+		"markdown_source": "../packages/warning/README.md",
+		"parent": "packages"
+	},
 	{
 		"title": "@wordpress/wordcount",
 		"slug": "packages-wordcount",

package.json

@@ -64,6 +64,7 @@
 		"@wordpress/token-list": "file:packages/token-list",
 		"@wordpress/url": "file:packages/url",
 		"@wordpress/viewport": "file:packages/viewport",
+		"@wordpress/warning": "file:packages/warning",
 		"@wordpress/wordcount": "file:packages/wordcount"
 	},
 	"devDependencies": {

packages/babel-preset-default/index.js

@@ -56,6 +56,7 @@ module.exports = function( api ) {
 		presets: [ getPresetEnv() ],
 		plugins: [
 			require.resolve( '@babel/plugin-proposal-object-rest-spread' ),
+			require.resolve( '@wordpress/warning/babel-plugin' ),
 			[
 				require.resolve( '@wordpress/babel-plugin-import-jsx-pragma' ),
 				{

packages/babel-preset-default/package.json

@@ -37,6 +37,7 @@
 		"@wordpress/babel-plugin-import-jsx-pragma": "file:../babel-plugin-import-jsx-pragma",
 		"@wordpress/browserslist-config": "file:../browserslist-config",
 		"@wordpress/element": "file:../element",
+		"@wordpress/warning": "file:../warning",
 		"core-js": "^3.1.4"
 	},
 	"publishConfig": {

packages/warning/.npmrc

@@ -0,0 +1 @@
+package-lock=false

packages/warning/README.md

@@ -0,0 +1,46 @@
+# Warning
+
+Utility for warning messages to the console based on a passed condition.
+
+## Installation
+
+Install the module
+
+```bash
+npm install @wordpress/warning --save
+```
+
+_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._
+
+## Reducing bundle size
+
+Literal strings aren't minified. Keeping them in your production bundle may increase the bundle size significantly. To prevent that, you can put `@wordpress/warning/babel-plugin` into your [babel config](https://babeljs.io/docs/en/plugins#plugin-options) or use [`@wordpress/babel-preset-default`](https://www.npmjs.com/package/@wordpress/babel-preset-default), which already includes the babel plugin.
+
+## API
+
+<!-- START TOKEN(Autogenerated API docs) -->
+
+<a name="default" href="#default">#</a> **default**
+
+Shows a warning with `messages` if `condition` passes and environment is not `production`.
+
+_Usage_
+
+```js
+import warning from '@wordpress/warning';
+
+function MyComponent( props ) {
+  warning( ! props.title, '`props.title` was not passed' );
+  ...
+}
+```
+
+_Parameters_
+
+-   _condition_ `boolean`: Whether the warning will be triggered or not.
+-   _messages_ `Array<string>`: Message(s) to show in the warning.
+
+
+<!-- END TOKEN(Autogenerated API docs) -->
+
+<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/warning/babel-plugin.js

@@ -0,0 +1 @@
+module.exports = require( './src/babel-plugin' );

packages/warning/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "@wordpress/warning",
+	"version": "0.0.1",
+	"description": "Warning utility for WordPress.",
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"warning"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/master/packages/warning/README.md",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "packages/warning"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"main": "build/index.js",
+	"module": "build-module/index.js",
+	"react-native": "src/index",
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	}
+}

packages/warning/src/babel-plugin.js

@@ -0,0 +1,62 @@
+const pkg = require( '../package.json' );
+
+function babelPlugin( { types: t } ) {
+	const seen = Symbol();
+
+	const binaryExpression = t.binaryExpression(
+		'!==',
+		t.memberExpression(
+			t.memberExpression( t.identifier( 'process' ), t.identifier( 'env' ), false ),
+			t.identifier( 'NODE_ENV' ),
+			false
+		),
+		t.stringLiteral( 'production' )
+	);
+
+	return {
+		visitor: {
+			ImportDeclaration( path, state ) {
+				const { node } = path;
+				const isThisPackageImport = node.source.value.indexOf( pkg.name ) !== -1;
+
+				if ( ! isThisPackageImport ) {
+					return;
+				}
+
+				const defaultSpecifier = node.specifiers.find(
+					( specifier ) => specifier.type === 'ImportDefaultSpecifier'
+				);
+
+				const { name } = defaultSpecifier.local;
+
+				state.callee = name;
+			},
+			CallExpression( path, state ) {
+				const { node } = path;
+
+				// Ignore if it's already been processed
+				if ( node[ seen ] ) {
+					return;
+				}
+
+				const name = state.callee || state.opts.callee;
+
+				if ( path.get( 'callee' ).isIdentifier( { name } ) ) {
+					// Turns this code:
+					// warning(condition, argument, argument);
+					// into this:
+					// process.env.NODE_ENV !== "production" ? warning(condition, argument, argument) : void 0;
+					node[ seen ] = true;
+					path.replaceWith(
+						t.ifStatement(
+							binaryExpression,
+							t.blockStatement( [ t.expressionStatement( node ) ] )
+						)
+					);
+				}
+			},
+		},
+	};
+}
+
+module.exports = babelPlugin;

packages/warning/src/index.js

@@ -0,0 +1,45 @@
+function isDev() {
+	return (
+		typeof process !== 'undefined' &&
+		process.env &&
+		process.env.NODE_ENV !== 'production'
+	);
+}
+
+/**
+ * Shows a warning with `messages` if `condition` passes and environment is not `production`.
+ *
+ * @param {boolean} condition Whether the warning will be triggered or not.
+ * @param {string[]} messages Message(s) to show in the warning.
+ *
+ * @example
+ * ```js
+ * import warning from '@wordpress/warning';
+ *
+ * function MyComponent( props ) {
+ *   warning( ! props.title, '`props.title` was not passed' );
+ *   ...
+ * }
+ * ```
+ */
+export default function warning( condition, ...messages ) {
+	if ( isDev() ) {
+		if ( ! condition ) {
+			return;
+		}
+
+		const text = messages.join( '\n' );
+
+		// eslint-disable-next-line no-console
+		console.warn( text );
+
+		// Throwing an error and catching it immediately to improve debugging
+		// A consumer can use 'pause on caught exceptions'
+		// https://github.com/facebook/react/issues/4216
+		try {
+			throw Error( text );
+		} catch ( x ) {
+			// do nothing
+		}
+	}
+}

packages/warning/src/test/babel-plugin.js

@@ -0,0 +1,102 @@
+/**
+ * External dependencies
+ */
+import { transform } from '@babel/core';
+
+/**
+ * Internal dependencies
+ */
+import babelPlugin from '../babel-plugin';
+
+function join( ...strings ) {
+	return strings.join( '\n' );
+}
+
+function compare( input, output, options = {} ) {
+	const { code } = transform( input, {
+		configFile: false,
+		plugins: [ [ babelPlugin, options ] ],
+	} );
+	expect( code ).toEqual( output );
+}
+
+describe( 'babel-plugin', function() {
+	it( 'should replace warning calls with import declaration', () => {
+		compare(
+			join(
+				'import warning from "@wordpress/warning";',
+				'warning(true, "a", "b");'
+			),
+			join(
+				'import warning from "@wordpress/warning";',
+				'process.env.NODE_ENV !== "production" ? warning(true, "a", "b") : void 0;'
+			)
+		);
+	} );
+
+	it( 'should not replace warning calls without import declaration', () => {
+		compare(
+			'warning(true, "a", "b");',
+			'warning(true, "a", "b");'
+		);
+	} );
+
+	it( 'should replace warning calls without import declaration with plugin options', () => {
+		compare(
+			'warning(true, "a", "b");',
+			'process.env.NODE_ENV !== "production" ? warning(true, "a", "b") : void 0;',
+			{ callee: 'warning' }
+		);
+	} );
+
+	it( 'should replace multiple warning calls', () => {
+		compare(
+			join(
+				'import warning from "@wordpress/warning";',
+				'warning(true, "a", "b");',
+				'warning(false, "b", "a");',
+				'warning(cond, "c");',
+			),
+			join(
+				'import warning from "@wordpress/warning";',
+				'process.env.NODE_ENV !== "production" ? warning(true, "a", "b") : void 0;',
+				'process.env.NODE_ENV !== "production" ? warning(false, "b", "a") : void 0;',
+				'process.env.NODE_ENV !== "production" ? warning(cond, "c") : void 0;'
+			)
+		);
+	} );
+
+	it( 'should identify warning callee name', () => {
+		compare(
+			join(
+				'import warn from "@wordpress/warning";',
+				'warn(true, "a", "b");',
+				'warn(false, "b", "a");',
+				'warn(cond, "c");',
+			),
+			join(
+				'import warn from "@wordpress/warning";',
+				'process.env.NODE_ENV !== "production" ? warn(true, "a", "b") : void 0;',
+				'process.env.NODE_ENV !== "production" ? warn(false, "b", "a") : void 0;',
+				'process.env.NODE_ENV !== "production" ? warn(cond, "c") : void 0;'
+			)
+		);
+	} );
+
+	it( 'should identify warning callee name by ', () => {
+		compare(
+			join(
+				'import warn from "@wordpress/warning";',
+				'warn(true, "a", "b");',
+				'warn(false, "b", "a");',
+				'warn(cond, "c");',
+			),
+			join(
+				'import warn from "@wordpress/warning";',
+				'process.env.NODE_ENV !== "production" ? warn(true, "a", "b") : void 0;',
+				'process.env.NODE_ENV !== "production" ? warn(false, "b", "a") : void 0;',
+				'process.env.NODE_ENV !== "production" ? warn(cond, "c") : void 0;'
+			)
+		);
+	} );
+} );