Hook reference: Add SlotFill support (https://github.com/woocommerce/woocommerce-admin/pull/6833)

* add @slotFill to process

* add types

* committing data

* use filter instead of hook

* changelog

* add action type

* update paths to ignore builds and node_modules

* changelog

* Add action data type

Co-authored-by: Joshua T Flowers <joshuatf@gmail.com>

Co-authored-by: Joshua T Flowers <joshuatf@gmail.com>

plugins/woocommerce-admin/.eslintrc.js

@@ -9,7 +9,14 @@ module.exports = {
 		'@wordpress/valid-sprintf': 'warn',
 		'jsdoc/check-tag-names': [
 			'error',
-			{ definedTags: [ 'jest-environment', 'hook' ] },
+			{
+				definedTags: [
+					'jest-environment',
+					'filter',
+					'action',
+					'slotFill',
+				],
+			},
 		],
 		'import/no-extraneous-dependencies': 'warn',
 		'import/no-unresolved': 'warn',

plugins/woocommerce-admin/bin/hook-reference/data.js

@@ -4,9 +4,11 @@ const { parse } = require( 'comment-parser/lib' );
 const { relative, resolve } = require( 'path' );
 const chalk = require( 'chalk' );
 
+const dataTypes = [ 'action', 'filter', 'slotFill' ];
+
 const getHooks = ( parsedData ) =>
 	parsedData.filter( ( docBlock ) =>
-		docBlock.tags.some( ( tag ) => tag.tag === 'hook' )
+		docBlock.tags.some( ( tag ) => dataTypes.includes( tag.tag ) )
 	);
 
 const getSourceFile = ( file, commit, { source } ) => {
@@ -17,9 +19,10 @@ const getSourceFile = ( file, commit, { source } ) => {
 };
 
 const logProgress = ( fileName, { tags } ) => {
-	const hook = tags.find( ( tag ) => tag.tag === 'hook' );
+	const hook = tags.find( ( tag ) => dataTypes.includes( tag.tag ) );
 	console.log(
-		chalk.cyan( `${ hook.name } ` ) +
+		chalk.green( `@${ hook.tag } ` ) +
+			chalk.cyan( `${ hook.name } ` ) +
 			chalk.yellow( 'generated in ' ) +
 			chalk.yellow.underline( fileName )
 	);
@@ -51,12 +54,14 @@ const makeDocObjects = async ( path ) => {
 	const hooks = await prepareHooks( path );
 	return hooks.map( ( { description, tags, sourceFile } ) => {
 		const example = tags.find( ( tag ) => tag.tag === 'example' );
-		const hook = tags.find( ( tag ) => tag.tag === 'hook' );
+		const tag = tags.find( ( tag ) => dataTypes.includes( tag.tag ) );
+
 		return {
 			description,
 			sourceFile,
-			name: hook ? hook.name : '',
+			name: tag ? tag.name : '',
 			example: example ? example.description : '',
+			type: tag.tag,
 		};
 	} );
 };

plugins/woocommerce-admin/bin/hook-reference/data.json

@@ -1,8 +1,16 @@
 [
     {
         "description": "List of homepage stats enabled by default",
-        "sourceFile": "https://github.com/woocommerce/woocommerce-admin/blob/ff1a3cb2f3857cfa759fb3c93cedfe630dbd5510/client/homescreen/stats-overview/defaults.js#L5-L16",
+        "sourceFile": "https://github.com/woocommerce/woocommerce-admin/blob/6889e695d6bbeff1e0fb607339f83cce18ca6e59/client/homescreen/stats-overview/defaults.js#L5-L16",
         "name": "woocommerce_admin_homepage_default_stats",
-        "example": "addFilter( 'woocommerce_admin_homepage_default_stats', 'plugin-domain', ( defaultStats ) => defaultStats.filter( ( stat ) => stat !== 'jetpack/stats/views' ) );"
+        "example": "addFilter( 'woocommerce_admin_homepage_default_stats', 'plugin-domain', ( defaultStats ) => defaultStats.filter( ( stat ) => stat !== 'jetpack/stats/views' ) );",
+        "type": "filter"
+    },
+    {
+        "description": "Create a Fill for extensions to add client facing custom Navigation Items.",
+        "sourceFile": "https://github.com/woocommerce/woocommerce-admin/blob/6889e695d6bbeff1e0fb607339f83cce18ca6e59/packages/navigation/src/index.js#L254-L270",
+        "name": "WooNavigationItem",
+        "example": "const MyExtenstionNavItem = () => ( <WooNavigationItem item=\"my-extension\">My Extension</WooNavigationItem> ); registerPlugin( 'my-extension', { render: MyExtenstionNavItem, scope: 'woocommerce-admin', } );",
+        "type": "slotFill"
     }
 ]

plugins/woocommerce-admin/bin/hook-reference/index.js

@@ -1,4 +1,3 @@
-const fs = require( 'fs' );
 const { stat, readdir, writeFile } = require( 'fs' ).promises;
 const { resolve } = require( 'path' );
 const createData = require( './data' );
@@ -9,12 +8,32 @@ async function getFilePaths( dir ) {
 	const files = await Promise.all(
 		subdirs.map( async ( subdir ) => {
 			const res = resolve( dir, subdir );
-			return ( await stat( res ) ).isDirectory()
-				? getFilePaths( res )
-				: res;
+			const _stat = await stat( res );
+			const isDir = _stat.isDirectory();
+			const isNotSourceDir =
+				isDir &&
+				/\/(build|build-module|build-style|node_modules)$/g.test( res );
+
+			if ( isNotSourceDir ) {
+				return;
+			}
+
+			return isDir ? getFilePaths( res ) : res;
 		} )
 	);
-	return files.reduce( ( a, f ) => a.concat( f ), [] );
+	return files
+		.filter( ( f ) => !! f )
+		.reduce( ( a, f ) => a.concat( f ), [] );
+}
+
+async function getAllFilePaths( paths ) {
+	const allFiles = await Promise.all(
+		paths.map( async ( path ) => {
+			return await getFilePaths( path );
+		} )
+	);
+
+	return allFiles.reduce( ( a, f ) => a.concat( f ), [] );
 }
 
 const writeJSONFile = async ( data ) => {
@@ -33,7 +52,7 @@ const writeJSONFile = async ( data ) => {
 console.log( chalk.green( 'Preparing Hook Reference data file' ) );
 console.log( '\n' );
 
-getFilePaths( 'client' )
+getAllFilePaths( [ 'client', 'packages' ] )
 	.then( ( paths ) => createData( paths ) )
 	.then( ( data ) => writeJSONFile( data ) )
 	.catch( ( e ) => console.error( e ) );

plugins/woocommerce-admin/client/homescreen/stats-overview/defaults.js

@@ -5,7 +5,7 @@ import { applyFilters } from '@wordpress/hooks';
 /**
  * List of homepage stats enabled by default
  *
- * @hook woocommerce_admin_homepage_default_stats
+ * @filter woocommerce_admin_homepage_default_stats
  * @example
  * addFilter(
  *	'woocommerce_admin_homepage_default_stats',

plugins/woocommerce-admin/packages/navigation/src/index.js

@@ -254,6 +254,16 @@ export const addHistoryListener = ( listener ) => {
 /**
  * Create a Fill for extensions to add client facing custom Navigation Items.
  *
+ * @slotFill WooNavigationItem
+ * @example
+ * const MyExtenstionNavItem = () => (
+ * 	<WooNavigationItem item="my-extension">My Extension</WooNavigationItem>
+ * );
+ *
+ * registerPlugin( 'my-extension', {
+ * 	render: MyExtenstionNavItem,
+ * 	scope: 'woocommerce-admin',
+ * } );
  * @param {Object} param0
  * @param {Array} param0.children - Node children.
  * @param {string} param0.item - Navigation item slug.

plugins/woocommerce-admin/readme.txt

@@ -79,6 +79,7 @@ Release and roadmap notes are available on the [WooCommerce Developers Blog](htt
 - Add: Add payment gateway suggestion unit tests #7142
 - Add: Feature toggle to disable Analytics UI #7168
 - Add: SlotFill to Abbreviated Notification panel #7091
+- Add: Hook reference slotFill support #6833
 - Dev: Add `woocommerce_admin_export_id` filter for customizing the export file name #7178
 - Dev: Remove old payment gateway task components #7224
 - Fix: Currency display on Orders activity card on homescreen #7181
@@ -269,6 +270,7 @@ Release and roadmap notes are available on the [WooCommerce Developers Blog](htt
 - Update: UI updates to Payment Task screen #6766
 - Update: Update payment gateway suggestions semantics to be more consistent #7130
 - Update: Adding setup required icon for non-configured payment methods #6811
+- Update: Add SlotFill support in hook reference script #6833
 
 == 2.2.6 5/7/2021 ==