doAction when a deprecated feature is encountered (#8110)

* doAction when a deprecated feature is encountered

* explicitly add hooks Dependency

* reinitialize options to pass to action

* reference hooks with file instead of version

* Add dependecny for wp-hooks to wp-deprecated

* clean up how options is constructed/deconstructed

* fix spacing

* add unit test for deprecation action

* fix new test

* include assertion for console warning

* update package-lock.json for hooks in deprecated

* document wp.deprecated hook

* Hooks: Update hook name and add usage example

* Add CHANGELOG.md file with the note about this feature

* Change order of import statement groups in test file

lib/client-assets.php

@@ -201,7 +201,7 @@ function gutenberg_register_scripts_and_styles() {
 	wp_register_script(
 		'wp-deprecated',
 		gutenberg_url( 'build/deprecated/index.js' ),
-		array(),
+		array( 'wp-hooks' ),
 		filemtime( gutenberg_dir_path() . 'build/deprecated/index.js' ),
 		true
 	);

packages/deprecated/CHANGELOG.md

@@ -0,0 +1,5 @@
+## 1.1.0 (Unreleased)
+
+### New Feature
+
+- Call `doAction` hook when a deprecated feature is encountered ([#8110](https://github.com/WordPress/gutenberg/pull/8110))

packages/deprecated/README.md

@@ -25,4 +25,20 @@ deprecated( 'Eating meat', {
 // Logs: 'Eating meat is deprecated and will be removed from the earth in the future. Please use vegetables instead. Note: You may find it beneficial to transition gradually.'
 ```
 
+## Hook
+
+The `deprecated` action is fired with three parameters: the name of the deprecated feature, the options object passed to deprecated, and the message sent to the console.
+
+_Example:_
+
+```js
+import { addAction } from '@wordpress/hooks';
+
+function addDeprecationAlert( message, { version } ) {
+	alert( `Deprecation: ${ message }. Version: ${ version }` );	
+}
+
+addAction( 'deprecated', 'my-plugin/add-deprecation-alert', addDeprecationAlert );
+```
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/deprecated/package.json

@@ -19,7 +19,8 @@
 	"main": "build/index.js",
 	"module": "build-module/index.js",
 	"dependencies": {
-		"@babel/runtime-corejs2": "7.0.0-beta.56"
+		"@babel/runtime-corejs2": "7.0.0-beta.56",
+		"@wordpress/hooks": "file:../hooks"
 	},
 	"publishConfig": {
 		"access": "public"

packages/deprecated/src/index.js

@@ -1,3 +1,8 @@
+/**
+ * WordPress dependencies
+ */
+import { doAction } from '@wordpress/hooks';
+
 /**
  * Object map tracking messages which have been logged, for use in ensuring a
  * message is only logged once.
@@ -17,7 +22,15 @@ export const logged = Object.create( null );
  * @param {?string} options.link        Link to documentation
  * @param {?string} options.hint        Additional message to help transition away from the deprecated feature.
  */
-export default function deprecated( feature, { version, alternative, plugin, link, hint } = {} ) {
+export default function deprecated( feature, options = {} ) {
+	const {
+		version,
+		alternative,
+		plugin,
+		link,
+		hint,
+	} = options;
+
 	const pluginMessage = plugin ? ` from ${ plugin }` : '';
 	const versionMessage = version ? `${ pluginMessage } in ${ version }` : '';
 	const useInsteadMessage = alternative ? ` Please use ${ alternative } instead.` : '';
@@ -30,6 +43,20 @@ export default function deprecated( feature, { version, alternative, plugin, lin
 		return;
 	}
 
+	/**
+	 * Fires whenever a deprecated feature is encountered
+	 *
+	 * @param {string}  feature             Name of the deprecated feature.
+	 * @param {?Object} options             Personalisation options
+	 * @param {?string} options.version     Version in which the feature will be removed.
+	 * @param {?string} options.alternative Feature to use instead
+	 * @param {?string} options.plugin      Plugin name if it's a plugin feature
+	 * @param {?string} options.link        Link to documentation
+	 * @param {?string} options.hint        Additional message to help transition away from the deprecated feature.
+	 * @param {?string} message             Message sent to console.warn
+	 */
+	doAction( 'deprecated', feature, options, message );
+
 	// eslint-disable-next-line no-console
 	console.warn( message );
 

packages/deprecated/src/test/index.js

@@ -1,3 +1,8 @@
+/**
+ * WordPress dependencies
+ */
+import { didAction } from '@wordpress/hooks';
+
 /**
  * Internal dependencies
  */
@@ -80,4 +85,11 @@ describe( 'deprecated', () => {
 		// eslint-disable-next-line no-console
 		expect( console.warn ).toHaveBeenCalledTimes( 1 );
 	} );
+
+	it( 'should do an action', () => {
+		deprecated( 'turkey', { alternative: 'tofurky' } );
+
+		expect( console ).toHaveWarned();
+		expect( didAction( 'deprecated' ) ).toBeTruthy();
+	} );
 } );