Add warning package

babel.config.js

@@ -6,6 +6,7 @@ module.exports = function( api ) {
 		plugins: [
 			'babel-plugin-emotion',
 			'babel-plugin-inline-json-import',
+			'babel-plugin-dev-expression',
 		],
 	};
 };

bin/api-docs/packages.js

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

docs/manifest-devhub.json

@@ -1475,6 +1475,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": {
@@ -102,6 +103,7 @@
 		"@wordpress/postcss-themes": "file:packages/postcss-themes",
 		"@wordpress/scripts": "file:packages/scripts",
 		"babel-loader": "8.0.6",
+		"babel-plugin-dev-expression": "0.2.2",
 		"babel-plugin-emotion": "10.0.23",
 		"babel-plugin-inline-json-import": "0.3.2",
 		"babel-plugin-react-native-classname-to-style": "1.2.2",

packages/warning/.npmrc

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

packages/warning/README.md

@@ -0,0 +1,44 @@
+# Warning
+
+Utility for warning messages to the console based on a passed condition.
+
+## Installation
+
+Install the module
+
+```bash
+npm install @wordpress/warning --save
+```
+
+This is recommended to use in conjunction with [`babel-plugin-dev-expression`](https://github.com/4Catalyzer/babel-plugin-dev-expression) so your warning messages won't end up in your production bundle.
+
+_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)._
+
+## 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/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/index.js

@@ -0,0 +1,37 @@
+/**
+ * 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 ( process.env.NODE_ENV !== 'production' ) {
+		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/index.js

@@ -0,0 +1,30 @@
+/**
+ * Internal dependencies
+ */
+import warning from '..';
+
+const initialNodeEnv = process.env.NODE_ENV;
+
+describe( 'warning', () => {
+	afterEach( () => {
+		process.env.NODE_ENV = initialNodeEnv;
+	} );
+
+	it( 'logs to console.warn when NODE_ENV is not "production"', () => {
+		process.env.NODE_ENV = 'development';
+		warning( true, 'warn', 'ing' );
+		expect( console ).toHaveWarnedWith( 'warn\ning' );
+	} );
+
+	it( 'does not log to console.warn if NODE_ENV is "production"', () => {
+		process.env.NODE_ENV = 'production';
+		warning( true, 'warn', 'ing' );
+		expect( console ).not.toHaveWarned();
+	} );
+
+	it( 'does not log to console.warn if condition is falsy', () => {
+		process.env.NODE_ENV = 'development';
+		warning( false, 'warn', 'ing' );
+		expect( console ).not.toHaveWarned();
+	} );
+} );