ESLint plugin: Remove temporary listed types for TypeScript validatio…

…n (p. 1) (#18808) * ESLint plugin: Remove temporary listed types for TypeScript validation * Fix import statements * E2E Test Utils: Fix return type for ElementHandle promise * Docs: Update API after JSDoc changes
WordPress · Dec 3, 2019 · c8c6903 · c8c6903
1 parent c0ba214
commit c8c6903
Show file tree

Hide file tree

Showing 22 changed files with 81 additions and 51 deletions.
diff --git a/packages/block-editor/src/components/provider/index.js b/packages/block-editor/src/components/provider/index.js
@@ -15,6 +15,8 @@ import { compose } from '@wordpress/compose';
  */
 import withRegistryProvider from './with-registry-provider';
 
+/** @typedef {import('@wordpress/data').WPDataRegistry} WPDataRegistry */
+
 class BlockEditorProvider extends Component {
 	componentDidMount() {
 		this.props.updateSettings( this.props.settings );

diff --git a/packages/block-editor/src/components/provider/index.native.js b/packages/block-editor/src/components/provider/index.native.js
@@ -6,6 +6,8 @@ import { SlotFillProvider } from '@wordpress/components';
 import { withDispatch, RegistryConsumer } from '@wordpress/data';
 import { createHigherOrderComponent, compose } from '@wordpress/compose';
 
+/** @typedef {import('@wordpress/data').WPDataRegistry} WPDataRegistry */
+
 /**
  * Higher-order component which renders the original component with the current
  * registry context passed as its `registry` prop.

diff --git a/packages/block-editor/src/components/typewriter/index.js b/packages/block-editor/src/components/typewriter/index.js
@@ -6,6 +6,8 @@ import { computeCaretRect, getScrollContainer } from '@wordpress/dom';
 import { withSelect } from '@wordpress/data';
 import { UP, DOWN, LEFT, RIGHT } from '@wordpress/keycodes';
 
+/** @typedef {import('@wordpress/element').WPSyntheticEvent} WPSyntheticEvent */
+
 const isIE = window.navigator.userAgent.indexOf( 'Trident' ) !== -1;
 const arrowKeyCodes = new Set( [ UP, DOWN, LEFT, RIGHT ] );
 const initialTriggerPercentage = 0.75;

diff --git a/packages/data/src/factory.js b/packages/data/src/factory.js
@@ -3,6 +3,8 @@
  */
 import defaultRegistry from './default-registry';
 
+/** @typedef {import('./registry').WPDataRegistry} WPDataRegistry */
+
 /**
  * Mark a selector as a registry selector.
  *

diff --git a/packages/data/src/plugins/persistence/index.js b/packages/data/src/plugins/persistence/index.js
@@ -9,6 +9,10 @@ import { merge, isPlainObject, get } from 'lodash';
 import defaultStorage from './storage/default';
 import { combineReducers } from '../../';
 
+/** @typedef {import('../../registry').WPDataRegistry} WPDataRegistry */
+
+/** @typedef {import('../../registry').WPDataPlugin} WPDataPlugin */
+
 /**
  * @typedef {Object} WPDataPersistencePluginOptions Persistence plugin options.
  *

diff --git a/packages/data/src/resolvers-cache-middleware.js b/packages/data/src/resolvers-cache-middleware.js
@@ -3,6 +3,8 @@
  */
 import { get } from 'lodash';
 
+/** @typedef {import('./registry').WPDataRegistry} WPDataRegistry */
+
 /**
  * Creates a middleware handling resolvers cache invalidation.
  *

diff --git a/packages/date/README.md b/packages/date/README.md
@@ -23,7 +23,7 @@ Formats a date (like `date()` in PHP), in the site's timezone.
 _Parameters_
 
 -   _dateFormat_ `string`: PHP-style formatting string. See php.net/date.
--   _dateValue_ `(Date|string|moment.Moment|null)`: Date object or string, parsable by moment.js.
+-   _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js.
 
 _Returns_
 
@@ -36,7 +36,7 @@ Formats a date (like `date_i18n()` in PHP).
 _Parameters_
 
 -   _dateFormat_ `string`: PHP-style formatting string. See php.net/date.
--   _dateValue_ `(Date|string|moment.Moment|null)`: Date object or string, parsable by moment.js.
+-   _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js.
 -   _gmt_ `boolean`: True for GMT/UTC, false for site's timezone.
 
 _Returns_
@@ -50,7 +50,7 @@ Formats a date. Does not alter the date's timezone.
 _Parameters_
 
 -   _dateFormat_ `string`: PHP-style formatting string. See php.net/date.
--   _dateValue_ `(Date|string|moment.Moment|null)`: Date object or string, parsable by moment.js.
+-   _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js.
 
 _Returns_
 
@@ -75,7 +75,7 @@ Formats a date (like `date()` in PHP), in the UTC timezone.
 _Parameters_
 
 -   _dateFormat_ `string`: PHP-style formatting string. See php.net/date.
--   _dateValue_ `(Date|string|moment.Moment|null)`: Date object or string, parsable by moment.js.
+-   _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js.
 
 _Returns_
 

diff --git a/packages/date/src/index.js b/packages/date/src/index.js
@@ -5,6 +5,8 @@ import momentLib from 'moment';
 import 'moment-timezone/moment-timezone';
 import 'moment-timezone/moment-timezone-utils';
 
+/** @typedef {import('moment').Moment} Moment */
+
 const WP_ZONE = 'WP';
 
 // Changes made here will likely need to be made in `lib/client-assets.php` as
@@ -145,7 +147,7 @@ const formatMap = {
 	/**
 	 * Gets the ordinal suffix.
 	 *
-	 * @param {moment.Moment} momentDate Moment instance.
+	 * @param {Moment} momentDate Moment instance.
 	 *
 	 * @return {string} Formatted date.
 	 */
@@ -160,7 +162,7 @@ const formatMap = {
 	/**
 	 * Gets the day of the year (zero-indexed).
 	 *
-	 * @param {moment.Moment} momentDate Moment instance.
+	 * @param {Moment} momentDate Moment instance.
 	 *
 	 * @return {string} Formatted date.
 	 */
@@ -180,7 +182,7 @@ const formatMap = {
 	/**
 	 * Gets the days in the month.
 	 *
-	 * @param {moment.Moment} momentDate Moment instance.
+	 * @param {Moment} momentDate Moment instance.
 	 *
 	 * @return {string} Formatted date.
 	 */
@@ -192,7 +194,7 @@ const formatMap = {
 	/**
 	 * Gets whether the current year is a leap year.
 	 *
-	 * @param {moment.Moment} momentDate Moment instance.
+	 * @param {Moment} momentDate Moment instance.
 	 *
 	 * @return {string} Formatted date.
 	 */
@@ -209,7 +211,7 @@ const formatMap = {
 	/**
 	 * Gets the current time in Swatch Internet Time (.beats).
 	 *
-	 * @param {moment.Moment} momentDate Moment instance.
+	 * @param {Moment} momentDate Moment instance.
 	 *
 	 * @return {string} Formatted date.
 	 */
@@ -240,7 +242,7 @@ const formatMap = {
 	/**
 	 * Gets whether the timezone is in DST currently.
 	 *
-	 * @param {moment.Moment} momentDate Moment instance.
+	 * @param {Moment} momentDate Moment instance.
 	 *
 	 * @return {string} Formatted date.
 	 */
@@ -253,7 +255,7 @@ const formatMap = {
 	/**
 	 * Gets the timezone offset in seconds.
 	 *
-	 * @param {moment.Moment} momentDate Moment instance.
+	 * @param {Moment} momentDate Moment instance.
 	 *
 	 * @return {string} Formatted date.
 	 */
@@ -275,7 +277,7 @@ const formatMap = {
  *
  * @param {string}                           dateFormat PHP-style formatting string.
  *                                                      See php.net/date.
- * @param {(Date|string|moment.Moment|null)} dateValue  Date object or string,
+ * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
  *                                                      parsable by moment.js.
  *
  * @return {string} Formatted date.
@@ -316,7 +318,7 @@ export function format( dateFormat, dateValue = new Date() ) {
  *
  * @param {string}                           dateFormat PHP-style formatting string.
  *                                                      See php.net/date.
- * @param {(Date|string|moment.Moment|null)} dateValue  Date object or string,
+ * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
  *                                                      parsable by moment.js.
  *
  * @return {string} Formatted date.
@@ -332,7 +334,7 @@ export function date( dateFormat, dateValue = new Date() ) {
  *
  * @param {string}                           dateFormat PHP-style formatting string.
  *                                                      See php.net/date.
- * @param {(Date|string|moment.Moment|null)} dateValue  Date object or string,
+ * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
  *                                                      parsable by moment.js.
  *
  * @return {string} Formatted date.
@@ -347,7 +349,7 @@ export function gmdate( dateFormat, dateValue = new Date() ) {
  *
  * @param {string}                           dateFormat PHP-style formatting string.
  *                                                      See php.net/date.
- * @param {(Date|string|moment.Moment|null)} dateValue  Date object or string,
+ * @param {(Date|string|Moment|null)}        dateValue  Date object or string,
  *                                                      parsable by moment.js.
  * @param {boolean}                          gmt        True for GMT/UTC, false for
  *                                                      site's timezone.

diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md
@@ -192,7 +192,7 @@ _Parameters_
 
 _Returns_
 
--   `?puppeteer.ElementHandle`: Object that represents an in-page DOM element.
+-   `?ElementHandle`: Object that represents an in-page DOM element.
 
 <a name="findSidebarPanelWithTitle" href="#findSidebarPanelWithTitle">#</a> **findSidebarPanelWithTitle**
 
@@ -204,7 +204,7 @@ _Parameters_
 
 _Returns_
 
--   `?puppeteer.ElementHandle`: Object that represents an in-page DOM element.
+-   `Promise<(ElementHandle|undefined)>`: Object that represents an in-page DOM element.
 
 <a name="getAllBlockInserterItemTitles" href="#getAllBlockInserterItemTitles">#</a> **getAllBlockInserterItemTitles**
 

diff --git a/packages/e2e-test-utils/src/enable-page-dialog-accept.js b/packages/e2e-test-utils/src/enable-page-dialog-accept.js
@@ -1,7 +1,9 @@
+/** @typedef {import('puppeteer').Dialog} Dialog */
+
 /**
  * Callback which automatically accepts dialog.
  *
- * @param {puppeteer.Dialog} dialog Dialog object dispatched by page via the 'dialog' event.
+ * @param {Dialog} dialog Dialog object dispatched by page via the 'dialog' event.
  */
 async function acceptPageDialog( dialog ) {
 	await dialog.accept();

diff --git a/packages/e2e-test-utils/src/find-sidebar-panel-toggle-button-with-title.js b/packages/e2e-test-utils/src/find-sidebar-panel-toggle-button-with-title.js
@@ -3,12 +3,14 @@
  */
 import { first } from 'lodash';
 
+/** @typedef {import('puppeteer').ElementHandle} ElementHandle */
+
 /**
  * Finds a sidebar panel with the provided title.
  *
  * @param {string} panelTitle The name of sidebar panel.
  *
- * @return {?puppeteer.ElementHandle} Object that represents an in-page DOM element.
+ * @return {?ElementHandle} Object that represents an in-page DOM element.
  */
 export async function findSidebarPanelToggleButtonWithTitle( panelTitle ) {
 	return first( await page.$x( `//div[contains(@class,"edit-post-sidebar")]//button[@class="components-button components-panel__body-toggle"][contains(text(),"${ panelTitle }")]` ) );

diff --git a/packages/e2e-test-utils/src/find-sidebar-panel-with-title.js b/packages/e2e-test-utils/src/find-sidebar-panel-with-title.js
@@ -3,16 +3,18 @@
  */
 import { first } from 'lodash';
 
+/** @typedef {import('puppeteer').ElementHandle} ElementHandle */
+
 /**
  * Finds the button responsible for toggling the sidebar panel with the provided title.
  *
  * @param {string} panelTitle The name of sidebar panel.
  *
- * @return {?puppeteer.ElementHandle} Object that represents an in-page DOM element.
+ * @return {Promise<ElementHandle|undefined>} Object that represents an in-page DOM element.
  */
 export async function findSidebarPanelWithTitle( panelTitle ) {
 	const classSelect = ( className ) => `[contains(concat(" ", @class, " "), " ${ className } ")]`;
 	const buttonSelector = `//div${ classSelect( 'edit-post-sidebar' ) }//button${ classSelect( 'components-button' ) }${ classSelect( 'components-panel__body-toggle' ) }[contains(text(),"${ panelTitle }")]`;
 	const panelSelector = `${ buttonSelector }/ancestor::*[contains(concat(" ", @class, " "), " components-panel__body ")]`;
-	return first( await await page.$x( panelSelector ) );
+	return first( await page.$x( panelSelector ) );
 }
diff --git a/packages/e2e-tests/specs/editor/various/adding-blocks.test.js b/packages/e2e-tests/specs/editor/various/adding-blocks.test.js
@@ -10,6 +10,8 @@ import {
 	setBrowserViewport,
 } from '@wordpress/e2e-test-utils';
 
+/** @typedef {import('puppeteer').ElementHandle} ElementHandle */
+
 describe( 'adding blocks', () => {
 	beforeEach( async () => {
 		await createNewPost();
@@ -18,7 +20,7 @@ describe( 'adding blocks', () => {
 	/**
 	 * Given a Puppeteer ElementHandle, clicks below its bounding box.
 	 *
-	 * @param {puppeteer.ElementHandle} elementHandle Element handle.
+	 * @param {ElementHandle} elementHandle Element handle.
 	 *
 	 * @return {Promise} Promise resolving when click occurs.
 	 */

diff --git a/packages/e2e-tests/specs/editor/various/preview.test.js b/packages/e2e-tests/specs/editor/various/preview.test.js
@@ -17,6 +17,8 @@ import {
 	pressKeyWithModifier,
 } from '@wordpress/e2e-test-utils';
 
+/** @typedef {import('puppeteer').Page} Page */
+
 async function openPreviewPage( editorPage ) {
 	let openTabs = await browser.pages();
 	const expectedTabsCount = openTabs.length + 1;
@@ -40,7 +42,7 @@ async function openPreviewPage( editorPage ) {
  * Given a Puppeteer Page instance for a preview window, clicks Preview, and
  * awaits the window navigation.
  *
- * @param {puppeteer.Page} previewPage Page on which to await navigation.
+ * @param {Page} previewPage Page on which to await navigation.
  *
  * @return {Promise} Promise resolving once navigation completes.
  */

diff --git a/packages/editor/src/components/autocompleters/block.js b/packages/editor/src/components/autocompleters/block.js
@@ -10,6 +10,10 @@ import { select, dispatch } from '@wordpress/data';
 import { createBlock } from '@wordpress/blocks';
 import { BlockIcon } from '@wordpress/block-editor';
 
+/** @typedef {import('@wordpress/block-editor').WPEditorInserterItem} WPEditorInserterItem */
+
+/** @typedef {import('@wordpress/components').WPCompleter} WPCompleter */
+
 /**
  * Returns the client ID of the parent where a newly inserted block would be
  * placed.

diff --git a/packages/editor/src/components/autocompleters/user.js b/packages/editor/src/components/autocompleters/user.js
@@ -3,6 +3,8 @@
  */
 import apiFetch from '@wordpress/api-fetch';
 
+/** @typedef {import('@wordpress/components').WPCompleter} WPCompleter */
+
 /**
  * A user mentions completer.
  *

diff --git a/packages/element/src/react.js b/packages/element/src/react.js
@@ -31,19 +31,19 @@ import { isString } from 'lodash';
 /**
  * Object containing a React element.
  *
- * @typedef {react.ReactElement} WPElement
+ * @typedef {import('react').ReactElement} WPElement
  */
 
 /**
  * Object containing a React component.
  *
- * @typedef {react.Component} WPComponent
+ * @typedef {import('react').Component} WPComponent
  */
 
 /**
  * Object containing a React synthetic event.
  *
- * @typedef {react.SyntheticEvent} WPSyntheticEvent
+ * @typedef {import('react').SyntheticEvent} WPSyntheticEvent
  */
 
 /**

diff --git a/packages/eslint-plugin/configs/jsdoc.js b/packages/eslint-plugin/configs/jsdoc.js
@@ -20,22 +20,9 @@ const temporaryWordPressInternalTypes = [
 	'WPBlockTypeIcon',
 	'WPBlockTypeIconRender',
 	'WPBlockTypeIconDescriptor',
-	'WPDataPersistencePluginOptions',
-	'WPDataPlugin',
-	'WPDataRegistry',
 	'WPComponent',
-	'WPCompleter',
 	'WPElement',
-	'WPFormat',
-	'WPEditorInserterItem',
 	'WPIcon',
-	'WPNotice',
-	'WPNoticeAction',
-	'WPPlugin',
-	'WPShortcode',
-	'WPShortcodeAttrs',
-	'WPShortcodeMatch',
-	'WPSyntheticEvent',
 ];
 
 /**
@@ -47,9 +34,6 @@ const temporaryWordPressInternalTypes = [
 const temporaryExternalTypes = [
 	'DOMHighResTimeStamp',
 	'espree',
-	'moment',
-	'puppeteer',
-	'react',
 ];
 
 /**
-Original file line number
+Diff line change
@@ Expand Up / @@ -3,6 +3,8 @@ @@
      */
     import defaultRegistry from './default-registry';
+    /** @typedef {import('./registry').WPDataRegistry} WPDataRegistry */
     /**
      * Mark a selector as a registry selector.
      *
@@ Expand Down @@