From c8c6903d146a5334e00a08b83b0a963b876132b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Grzegorz=20=28Greg=29=20Zi=C3=B3=C5=82kowski?= Date: Tue, 3 Dec 2019 11:31:17 +0100 Subject: [PATCH] ESLint plugin: Remove temporary listed types for TypeScript validation (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 --- .../src/components/provider/index.js | 2 ++ .../src/components/provider/index.native.js | 2 ++ .../src/components/typewriter/index.js | 2 ++ packages/data/src/factory.js | 2 ++ .../data/src/plugins/persistence/index.js | 4 +++ .../data/src/resolvers-cache-middleware.js | 2 ++ packages/date/README.md | 8 +++--- packages/date/src/index.js | 24 +++++++++-------- packages/e2e-test-utils/README.md | 4 +-- .../src/enable-page-dialog-accept.js | 4 ++- ...-sidebar-panel-toggle-button-with-title.js | 4 ++- .../src/find-sidebar-panel-with-title.js | 6 +++-- .../editor/various/adding-blocks.test.js | 4 ++- .../specs/editor/various/preview.test.js | 4 ++- .../src/components/autocompleters/block.js | 4 +++ .../src/components/autocompleters/user.js | 2 ++ packages/element/src/react.js | 6 ++--- packages/eslint-plugin/configs/jsdoc.js | 16 ------------ packages/jest-puppeteer-axe/src/index.js | 26 ++++++++++++------- packages/notices/src/store/selectors.js | 2 ++ packages/rich-text/src/component/index.js | 2 ++ .../rich-text/src/unregister-format-type.js | 2 ++ 22 files changed, 81 insertions(+), 51 deletions(-) diff --git a/packages/block-editor/src/components/provider/index.js b/packages/block-editor/src/components/provider/index.js index ff3528d2520521..a9dfbf11430c60 100644 --- 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 index fca4fab5ddbdee..1d3d46467288c6 100644 --- 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 index 00270ba0eb6e9c..99487f7a31cf22 100644 --- 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 index bdc2f1519e60e5..2bb74724f56c92 100644 --- 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 index 871a7e56133594..49a49fc24302b2 100644 --- 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 index e7e0a2ae7c6201..0a51fb02f2015b 100644 --- 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 index 96cbbba1b7239d..e45bb664c85519 100644 --- 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 index 4537ec47284749..54fe5e633d8d29 100644 --- 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 index ed6b5ac157f652..d397bce0bf6470 100644 --- 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. # **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. # **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 index f8f2976de67a76..d09fc7f5e046d0 100644 --- 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 index 55fbf4c91c10f2..916ddc53f4b6b4 100644 --- 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 index 2f1436c5b8de23..fea4bf968f0a46 100644 --- 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} 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 index 4d05c6a68a51ab..c0e72c9dc63682 100644 --- 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 index 7467a9382ae48a..db92a0ff26e8c2 100644 --- 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 index 5311d01ec2b749..73ff5583873fae 100644 --- 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 index 1dea163ee16443..45eecce3b8e4de 100644 --- 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 index 2776f514b329e5..b24f30c5fbafbb 100644 --- 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 index 45c58d2891b4c9..bcc4cc42fb4070 100644 --- 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', ]; /** diff --git a/packages/jest-puppeteer-axe/src/index.js b/packages/jest-puppeteer-axe/src/index.js index 2ddcabcc7707bc..8ad73875e2ad69 100644 --- a/packages/jest-puppeteer-axe/src/index.js +++ b/packages/jest-puppeteer-axe/src/index.js @@ -3,6 +3,12 @@ */ import AxePuppeteer from 'axe-puppeteer'; +/** @typedef {import('puppeteer').Page} Page */ + +/** @typedef {import('axe-core').RunOptions} RunOptions */ + +/** @typedef {import('axe-core').Spec} Spec */ + /** * Formats the list of violations object returned by Axe analysis. * @@ -53,15 +59,17 @@ function formatViolations( violations ) { * * @see https://github.com/dequelabs/axe-puppeteer * - * @param {puppeteer.Page} page Puppeteer's page instance. - * @param {?Object} params Optional params that allow better control over Axe API. - * @param {?string|Array} params.include CSS selector(s) to add to the list of elements - * to include in analysis. - * @param {?string|Array} params.exclude CSS selector(s) to add to the list of elements - * to exclude from analysis. - * @param {?Array} params.disabledRules The list of Axe rules to skip from verification. - * @param {?Axe.RunOptions} params.options A flexible way to configure how Axe run operates, see https://github.com/dequelabs/axe-core/blob/master/doc/API.md#options-parameter. - * @param {?Axe.Spec} params.config Axe configuration object, see https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure. + * @param {Page} page Puppeteer's page instance. + * @param {?Object} params Optional params that allow better control over Axe API. + * @param {?string|Array} params.include CSS selector(s) to add to the list of elements + * to include in analysis. + * @param {?string|Array} params.exclude CSS selector(s) to add to the list of elements + * to exclude from analysis. + * @param {?Array} params.disabledRules The list of Axe rules to skip from verification. + * @param {?RunOptions} params.options A flexible way to configure how Axe run operates, + * see https://github.com/dequelabs/axe-core/blob/master/doc/API.md#options-parameter. + * @param {?Spec} params.config Axe configuration object, + * see https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure. * * @return {Object} A matcher object with two keys `pass` and `message`. */ diff --git a/packages/notices/src/store/selectors.js b/packages/notices/src/store/selectors.js index 358a159aa8dc66..879f745ffe06d0 100644 --- a/packages/notices/src/store/selectors.js +++ b/packages/notices/src/store/selectors.js @@ -3,6 +3,8 @@ */ import { DEFAULT_CONTEXT } from './constants'; +/** @typedef {import('./actions').WPNoticeAction} WPNoticeAction */ + /** * The default empty set of notices to return when there are no notices * assigned for a given notices context. This can occur if the getNotices diff --git a/packages/rich-text/src/component/index.js b/packages/rich-text/src/component/index.js index a71904801b1fca..66783ace871156 100644 --- a/packages/rich-text/src/component/index.js +++ b/packages/rich-text/src/component/index.js @@ -42,6 +42,8 @@ import { isEmptyLine } from '../is-empty'; const { getSelection, getComputedStyle } = window; +/** @typedef {import('@wordpress/element').WPSyntheticEvent} WPSyntheticEvent */ + /** * All inserting input types that would insert HTML into the DOM. * diff --git a/packages/rich-text/src/unregister-format-type.js b/packages/rich-text/src/unregister-format-type.js index a70c1d1d417f2b..aa0d4963b16bba 100644 --- a/packages/rich-text/src/unregister-format-type.js +++ b/packages/rich-text/src/unregister-format-type.js @@ -4,6 +4,8 @@ import { select, dispatch } from '@wordpress/data'; import { removeFilter } from '@wordpress/hooks'; +/** @typedef {import('./register-format-type').WPFormat} WPFormat */ + /** * Unregisters a format. *