From 920ec1dab556de6daa939481b19f4fcd06d484e5 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 18 Oct 2019 19:18:32 +0200 Subject: [PATCH 1/2] Code style: Fix ESLint warnings reported for JSDoc definitions --- .../developers/data/data-core-block-editor.md | 4 +- .../developers/data/data-core-edit-post.md | 4 +- .../developers/data/data-core-editor.md | 2 +- .../developers/data/data-core-nux.md | 2 +- .../developers/data/data-core.md | 2 +- packages/block-editor/README.md | 2 +- .../src/components/block-edit/context.js | 6 +-- .../src/components/block-list/breadcrumb.js | 2 +- .../src/components/block-preview/index.js | 2 +- .../src/components/colors/with-colors.js | 2 +- .../components/ignore-nested-events/index.js | 2 +- .../src/components/inserter/index.js | 4 +- .../src/components/inserter/index.native.js | 4 +- .../src/components/media-upload/index.js | 2 +- .../src/components/provider/index.js | 4 +- .../src/components/provider/index.native.js | 8 +-- .../rich-text/remove-browser-shortcuts.js | 4 +- .../src/components/typewriter/index.js | 2 +- packages/block-editor/src/hooks/anchor.js | 4 +- .../src/hooks/custom-class-name.js | 4 +- packages/block-editor/src/store/selectors.js | 24 +++++---- packages/block-library/src/columns/utils.js | 38 +++++++------- packages/blocks/README.md | 12 ++--- packages/blocks/src/api/children.js | 6 +-- packages/blocks/src/api/parser.js | 8 +-- packages/blocks/src/api/registration.js | 36 ++++++------- packages/blocks/src/api/serializer.js | 12 ++--- packages/blocks/src/api/utils.js | 10 ++-- .../src/block-content-provider/index.js | 4 +- packages/components/src/autocomplete/index.js | 2 +- packages/components/src/date-time/date.js | 2 +- .../higher-order/with-focus-return/index.js | 10 ++-- .../src/higher-order/with-notices/index.js | 5 +- .../with-spoken-messages/index.js | 4 +- packages/components/src/menu-item/index.js | 2 +- packages/components/src/modal/frame.js | 2 +- packages/components/src/modal/index.js | 2 +- packages/components/src/placeholder/README.md | 2 +- packages/components/src/scroll-lock/index.js | 2 +- packages/components/src/toolbar/index.js | 4 +- packages/compose/README.md | 14 +++--- .../compose/src/higher-order/pure/index.js | 2 +- .../higher-order/with-instance-id/index.js | 4 +- .../higher-order/with-safe-timeout/index.js | 4 +- .../src/higher-order/with-state/index.js | 2 +- .../create-higher-order-component/index.js | 2 +- packages/core-data/README.md | 2 +- packages/core-data/src/actions.js | 4 +- packages/data/README.md | 8 +-- .../src/components/with-dispatch/index.js | 2 +- .../src/components/with-registry/index.js | 4 +- .../data/src/components/with-select/index.js | 2 +- packages/data/src/factory.js | 2 +- packages/data/src/namespace-store/index.js | 20 ++++---- .../data/src/plugins/persistence/index.js | 6 +-- .../data/src/resolvers-cache-middleware.js | 8 +-- packages/date/README.md | 8 +-- packages/date/src/index.js | 50 +++++++++---------- packages/e2e-test-utils/README.md | 6 +-- .../src/enable-page-dialog-accept.js | 2 +- ...-sidebar-panel-toggle-button-with-title.js | 2 +- .../src/find-sidebar-panel-with-title.js | 2 +- .../src/wait-for-window-dimensions.js | 2 +- .../editor/various/adding-blocks.test.js | 2 +- .../specs/editor/various/preview.test.js | 2 +- packages/edit-post/README.md | 30 +++++------ .../plugin-block-settings-menu-item.js | 4 +- .../header/plugin-more-menu-item/index.js | 4 +- .../plugin-sidebar-more-menu-item/index.js | 4 +- .../plugin-document-setting-panel/index.js | 4 +- .../plugin-post-publish-panel/index.js | 4 +- .../sidebar/plugin-post-status-info/index.js | 2 +- .../sidebar/plugin-pre-publish-panel/index.js | 17 ++++--- .../sidebar/plugin-sidebar/index.js | 4 +- .../src/hooks/validate-multiple-use/index.js | 4 +- packages/edit-post/src/store/selectors.js | 4 +- .../widget-area/selection-observer.js | 2 +- .../src/components/autocompleters/block.js | 6 +-- .../src/components/autocompleters/user.js | 2 +- .../post-type-support-check/index.js | 14 +++--- packages/editor/src/store/actions.native.js | 4 +- packages/editor/src/store/reducer.js | 8 +-- packages/editor/src/store/selectors.js | 2 +- packages/element/README.md | 16 +++--- packages/element/src/raw-html.js | 2 +- packages/element/src/react-platform.js | 10 ++-- packages/element/src/react.js | 26 ++++++++-- packages/element/src/serialize.js | 6 +-- packages/jest-puppeteer-axe/src/index.js | 14 +++--- packages/notices/src/store/actions.js | 11 ++++ packages/notices/src/store/selectors.js | 13 +---- packages/nux/src/store/selectors.js | 4 +- packages/plugins/README.md | 16 +++--- packages/plugins/src/api/index.js | 30 ++++++++--- .../src/components/plugin-area/index.js | 2 +- .../src/components/plugin-context/index.js | 2 +- packages/rich-text/README.md | 8 +-- packages/rich-text/src/component/index.js | 16 +++--- .../rich-text/src/register-format-type.js | 19 +++++-- packages/rich-text/src/to-dom.js | 2 +- .../rich-text/src/unregister-format-type.js | 4 +- 101 files changed, 387 insertions(+), 348 deletions(-) diff --git a/docs/designers-developers/developers/data/data-core-block-editor.md b/docs/designers-developers/developers/data/data-core-block-editor.md index eb9201165dafd6..5d994934d64d7b 100644 --- a/docs/designers-developers/developers/data/data-core-block-editor.md +++ b/docs/designers-developers/developers/data/data-core-block-editor.md @@ -233,7 +233,7 @@ _Parameters_ _Returns_ -- `Array`: Block objects. +- `null`: Block objects. # **getBlockSelectionEnd** @@ -345,7 +345,7 @@ _Parameters_ _Returns_ -- `Array`: Items that appear in inserter. +- `Array`: Items that appear in inserter. # **getLastMultiSelectedBlockClientId** diff --git a/docs/designers-developers/developers/data/data-core-edit-post.md b/docs/designers-developers/developers/data/data-core-edit-post.md index 93efda1bd0bc4f..49801a69817be8 100644 --- a/docs/designers-developers/developers/data/data-core-edit-post.md +++ b/docs/designers-developers/developers/data/data-core-edit-post.md @@ -80,11 +80,11 @@ _Parameters_ - _state_ `Object`: Global application state. - _preferenceKey_ `string`: Preference Key. -- _defaultValue_ `Mixed`: Default Value. +- _defaultValue_ `*`: Default Value. _Returns_ -- `Mixed`: Preference Value. +- `*`: Preference Value. # **getPreferences** diff --git a/docs/designers-developers/developers/data/data-core-editor.md b/docs/designers-developers/developers/data/data-core-editor.md index 8b20edac6d37c1..29c1fc810e993f 100644 --- a/docs/designers-developers/developers/data/data-core-editor.md +++ b/docs/designers-developers/developers/data/data-core-editor.md @@ -203,7 +203,7 @@ _Parameters_ _Returns_ -- `Array`: Filtered set of blocks for save. +- `null`: Filtered set of blocks for save. # **getClientIdsOfDescendants** diff --git a/docs/designers-developers/developers/data/data-core-nux.md b/docs/designers-developers/developers/data/data-core-nux.md index e937601ec864b6..92dcf6be1d0ac2 100644 --- a/docs/designers-developers/developers/data/data-core-nux.md +++ b/docs/designers-developers/developers/data/data-core-nux.md @@ -30,7 +30,7 @@ _Parameters_ _Returns_ -- `?NUX.GuideInfo`: Information about the associated guide. +- `?NUXGuideInfo`: Information about the associated guide. # **isTipVisible** diff --git a/docs/designers-developers/developers/data/data-core.md b/docs/designers-developers/developers/data/data-core.md index ce0cda7d3542a3..79f3f41991c08f 100644 --- a/docs/designers-developers/developers/data/data-core.md +++ b/docs/designers-developers/developers/data/data-core.md @@ -512,7 +512,7 @@ a given URl has been received. _Parameters_ - _url_ `string`: URL to preview the embed for. -- _preview_ `Mixed`: Preview data. +- _preview_ `*`: Preview data. _Returns_ diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index 86ffa7887d2daf..e061490c7a6027 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -137,7 +137,7 @@ _Parameters_ _Returns_ -- `WPElement`: Rendered element. +- `null`: The component to be rendered. # **BlockSelectionClearer** diff --git a/packages/block-editor/src/components/block-edit/context.js b/packages/block-editor/src/components/block-edit/context.js index 863cdc3e5d6fa5..74f7f4c6ad4532 100644 --- a/packages/block-editor/src/components/block-edit/context.js +++ b/packages/block-editor/src/components/block-edit/context.js @@ -27,7 +27,7 @@ export { Provider as BlockEditContextProvider }; * expected to return object of props to * merge with the component's own props. * - * @return {Component} Enhanced component with injected context as props. + * @return {import('@wordpress/element').WPComponent} Enhanced component with injected context as props. */ export const withBlockEditContext = ( mapContextToProps ) => createHigherOrderComponent( ( OriginalComponent ) => { return ( props ) => ( @@ -46,9 +46,9 @@ export const withBlockEditContext = ( mapContextToProps ) => createHigherOrderCo * A Higher Order Component used to render conditionally the wrapped * component only when the BlockEdit has selected state set. * - * @param {Component} OriginalComponent Component to wrap. + * @param {import('@wordpress/element').WPComponent} OriginalComponent Component to wrap. * - * @return {Component} Component which renders only when the BlockEdit is selected. + * @return {import('@wordpress/element').WPComponent} Component which renders only when the BlockEdit is selected. */ export const ifBlockEditSelected = createHigherOrderComponent( ( OriginalComponent ) => { return ( props ) => ( diff --git a/packages/block-editor/src/components/block-list/breadcrumb.js b/packages/block-editor/src/components/block-list/breadcrumb.js index 81f05b40bf7080..56bc7e840d47ec 100644 --- a/packages/block-editor/src/components/block-list/breadcrumb.js +++ b/packages/block-editor/src/components/block-list/breadcrumb.js @@ -16,7 +16,7 @@ import BlockTitle from '../block-title'; * the root block. * * @param {string} props.clientId Client ID of block. - * @return {WPElement} Block Breadcrumb. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ const BlockBreadcrumb = forwardRef( ( { clientId }, ref ) => { const { setNavigationMode } = useDispatch( 'core/block-editor' ); diff --git a/packages/block-editor/src/components/block-preview/index.js b/packages/block-editor/src/components/block-preview/index.js index 8a6692a422a6f7..9e8fb4982d72b9 100644 --- a/packages/block-editor/src/components/block-preview/index.js +++ b/packages/block-editor/src/components/block-preview/index.js @@ -137,7 +137,7 @@ export function BlockPreview( { blocks, viewportWidth = 700, padding, settings } * * @param {Array|Object} blocks A block instance (object) or an array of blocks to be previewed. * @param {number} viewportWidth Width of the preview container in pixels. Controls at what size the blocks will be rendered inside the preview. Default: 700. - * @return {WPElement} Rendered element. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ export default withSelect( ( select ) => { return { diff --git a/packages/block-editor/src/components/colors/with-colors.js b/packages/block-editor/src/components/colors/with-colors.js index b6f33b1b8590f7..69d04f2f625189 100644 --- a/packages/block-editor/src/components/colors/with-colors.js +++ b/packages/block-editor/src/components/colors/with-colors.js @@ -49,7 +49,7 @@ const withEditorColorPalette = () => withSelect( ( select ) => { * @param {Array} colorTypes An array of color types (e.g. 'backgroundColor, borderColor). * @param {Function} withColorPalette A HOC for injecting the 'colors' prop into the WrappedComponent. * - * @return {Component} The component that can be used as a HOC. + * @return {import('@wordpress/element').WPComponent} The component that can be used as a HOC. */ function createColorHOC( colorTypes, withColorPalette ) { const colorMap = reduce( colorTypes, ( colorObject, colorType ) => { diff --git a/packages/block-editor/src/components/ignore-nested-events/index.js b/packages/block-editor/src/components/ignore-nested-events/index.js index 2592ba3abd0527..df1a49da069904 100644 --- a/packages/block-editor/src/components/ignore-nested-events/index.js +++ b/packages/block-editor/src/components/ignore-nested-events/index.js @@ -20,7 +20,7 @@ import { Component, forwardRef, createElement } from '@wordpress/element'; * element should stop propagation but not invoke a callback handler, since it * would be assumed these are invoked by the child element. * - * @type {Component} + * @type {import('@wordpress/element').WPComponent} */ export class IgnoreNestedEvents extends Component { constructor() { diff --git a/packages/block-editor/src/components/inserter/index.js b/packages/block-editor/src/components/inserter/index.js index 5abb1ae4ef9230..12eae37767fb21 100644 --- a/packages/block-editor/src/components/inserter/index.js +++ b/packages/block-editor/src/components/inserter/index.js @@ -51,7 +51,7 @@ class Inserter extends Component { * pressed. * @param {boolean} options.isOpen Whether dropdown is currently open. * - * @return {WPElement} Dropdown toggle element. + * @return {import('@wordpress/element').WPElement} Dropdown toggle element. */ renderToggle( { onToggle, isOpen } ) { const { @@ -69,7 +69,7 @@ class Inserter extends Component { * @param {Function} options.onClose Callback to invoke when dropdown is * closed. * - * @return {WPElement} Dropdown content element. + * @return {import('@wordpress/element').WPElement} Dropdown content element. */ renderContent( { onClose } ) { const { rootClientId, clientId, isAppender, showInserterHelpPanel } = this.props; diff --git a/packages/block-editor/src/components/inserter/index.native.js b/packages/block-editor/src/components/inserter/index.native.js index 4c06402af38214..0170d16577f912 100644 --- a/packages/block-editor/src/components/inserter/index.native.js +++ b/packages/block-editor/src/components/inserter/index.native.js @@ -50,7 +50,7 @@ class Inserter extends Component { * pressed. * @param {boolean} options.isOpen Whether dropdown is currently open. * - * @return {WPElement} Dropdown toggle element. + * @return {import('@wordpress/element').WPElement} Dropdown toggle element. */ renderToggle( { onToggle, isOpen } ) { const { @@ -69,7 +69,7 @@ class Inserter extends Component { * @param {Function} options.onClose Callback to invoke when dropdown is * closed. * - * @return {WPElement} Dropdown content element. + * @return {import('@wordpress/element').WPElement} Dropdown content element. */ renderContent( { onClose, isOpen } ) { const { rootClientId, clientId, isAppender } = this.props; diff --git a/packages/block-editor/src/components/media-upload/index.js b/packages/block-editor/src/components/media-upload/index.js index 1cb3e511097276..222aec5a301185 100644 --- a/packages/block-editor/src/components/media-upload/index.js +++ b/packages/block-editor/src/components/media-upload/index.js @@ -8,7 +8,7 @@ import { withFilters } from '@wordpress/components'; * an integration with the core blocks that handle media files. By default it renders nothing but * it provides a way to have it overridden with the `editor.MediaUpload` filter. * - * @return {WPElement} Media upload element. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ const MediaUpload = () => null; diff --git a/packages/block-editor/src/components/provider/index.js b/packages/block-editor/src/components/provider/index.js index 488dd6244d8c65..519e36d6410581 100644 --- a/packages/block-editor/src/components/provider/index.js +++ b/packages/block-editor/src/components/provider/index.js @@ -73,8 +73,8 @@ class BlockEditorProvider extends Component { * This needs to be done synchronously after state changes (instead of using * `componentDidUpdate`) in order to avoid batching these changes. * - * @param {WPDataRegistry} registry Registry from which block editor - * dispatch is to be overriden. + * @param {import('@wordpress/data').WPDataRegistry} registry Registry from which block editor + * dispatch is to be overridden. */ attachChangeObserver( registry ) { if ( this.unsubscribe ) { diff --git a/packages/block-editor/src/components/provider/index.native.js b/packages/block-editor/src/components/provider/index.native.js index 8e2f2e677397b4..eccb227e519650 100644 --- a/packages/block-editor/src/components/provider/index.native.js +++ b/packages/block-editor/src/components/provider/index.native.js @@ -10,9 +10,9 @@ import { createHigherOrderComponent, compose } from '@wordpress/compose'; * Higher-order component which renders the original component with the current * registry context passed as its `registry` prop. * - * @param {WPComponent} OriginalComponent Original component. + * @param {import('@wordpress/element').WPComponent} OriginalComponent Original component. * - * @return {WPComponent} Enhanced component. + * @return {import('@wordpress/element').WPComponent} Enhanced component. */ const withRegistry = createHigherOrderComponent( ( OriginalComponent ) => ( props ) => ( @@ -75,8 +75,8 @@ class BlockEditorProvider extends Component { * This needs to be done synchronously after state changes (instead of using * `componentDidUpdate`) in order to avoid batching these changes. * - * @param {WPDataRegistry} registry Registry from which block editor - * dispatch is to be overriden. + * @param {import('@wordpress/data').WPDataRegistry} registry Registry from which block editor + * dispatch is to be overridden. */ attachChangeObserver( registry ) { if ( this.unsubscribe ) { diff --git a/packages/block-editor/src/components/rich-text/remove-browser-shortcuts.js b/packages/block-editor/src/components/rich-text/remove-browser-shortcuts.js index 165566a5bbbd16..ee275d3edcccb5 100644 --- a/packages/block-editor/src/components/rich-text/remove-browser-shortcuts.js +++ b/packages/block-editor/src/components/rich-text/remove-browser-shortcuts.js @@ -25,7 +25,7 @@ const HANDLED_SHORTCUTS = [ * shortcuts. Since shortcuts never change, the element can be considered * static, and can be skipped in reconciliation. * - * @type {WPElement} + * @type {import('@wordpress/element').WPElement} */ const SHORTCUTS_ELEMENT = ( SHORTCUTS_ELEMENT; diff --git a/packages/block-editor/src/components/typewriter/index.js b/packages/block-editor/src/components/typewriter/index.js index 7600b2cd8747cd..d636d13e025baf 100644 --- a/packages/block-editor/src/components/typewriter/index.js +++ b/packages/block-editor/src/components/typewriter/index.js @@ -100,7 +100,7 @@ class Typewriter extends Component { * Maintains the scroll position after a selection change caused by a * keyboard event. * - * @param {SyntheticEvent} event Synthetic keyboard event. + * @param {import('@wordpress/element').WPSyntheticEvent} event Synthetic keyboard event. */ maintainCaretPosition( { keyCode } ) { if ( ! this.isSelectionEligibleForScroll() ) { diff --git a/packages/block-editor/src/hooks/anchor.js b/packages/block-editor/src/hooks/anchor.js index 9b78c39bbfeb02..15a9d060769bd4 100644 --- a/packages/block-editor/src/hooks/anchor.js +++ b/packages/block-editor/src/hooks/anchor.js @@ -56,9 +56,9 @@ export function addAttribute( settings ) { * Override the default edit UI to include a new block inspector control for * assigning the anchor ID, if block supports anchor. * - * @param {Function|Component} BlockEdit Original component. + * @param {import('@wordpress/element').WPComponent} BlockEdit Original component. * - * @return {string} Wrapped component. + * @return {import('@wordpress/element').WPComponent} Wrapped component. */ export const withInspectorControl = createHigherOrderComponent( ( BlockEdit ) => { return ( props ) => { diff --git a/packages/block-editor/src/hooks/custom-class-name.js b/packages/block-editor/src/hooks/custom-class-name.js index bac77a37ea42a2..17792d692f8947 100644 --- a/packages/block-editor/src/hooks/custom-class-name.js +++ b/packages/block-editor/src/hooks/custom-class-name.js @@ -47,9 +47,9 @@ export function addAttribute( settings ) { * Override the default edit UI to include a new block inspector control for * assigning the custom class name, if block supports custom class name. * - * @param {Function|Component} BlockEdit Original component. + * @param {import('@wordpress/element').WPComponent} BlockEdit Original component. * - * @return {string} Wrapped component. + * @return {import('@wordpress/element').WPComponent} Wrapped component. */ export const withInspectorControl = createHigherOrderComponent( ( BlockEdit ) => { return ( props ) => { diff --git a/packages/block-editor/src/store/selectors.js b/packages/block-editor/src/store/selectors.js index 7f03542fd841da..09cbcf261ebb39 100644 --- a/packages/block-editor/src/store/selectors.js +++ b/packages/block-editor/src/store/selectors.js @@ -29,6 +29,16 @@ import { } from '@wordpress/blocks'; import { SVG, Rect, G, Path } from '@wordpress/components'; +/** + * A block selection object. + * + * @typedef {Object} WPBlockSelection + * + * @property {string} clientId A block client ID. + * @property {string} attributeKey A block attribute key. + * @property {number} offset A block attribute offset. + */ + // Module constants /** @@ -255,7 +265,7 @@ export const getGlobalBlockCount = createSelector( * @param {Object} state Editor state. * @param {string[]} clientIds Client IDs for which blocks are to be returned. * - * @return {WPBlock[]} Block objects. + * @return {import('@wordpress/blocks').WPBlockType[]} Block objects. */ export const getBlocksByClientId = createSelector( ( state, clientIds ) => map( @@ -281,14 +291,6 @@ export function getBlockCount( state, rootClientId ) { return getBlockOrder( state, rootClientId ).length; } -/** - * @typedef {WPBlockSelection} A block selection object. - * - * @property {string} clientId A block client ID. - * @property {string} attributeKey A block attribute key. - * @property {number} offset A block attribute offset. - */ - /** * Returns the current selection start block client ID, attribute key and text * offset. @@ -1123,9 +1125,9 @@ const canIncludeBlockTypeInInserter = ( state, blockType, rootClientId ) => { * @param {Object} state Editor state. * @param {?string} rootClientId Optional root client ID of block list. * - * @return {Editor.InserterItem[]} Items that appear in inserter. + * @return {EditorInserterItem[]} Items that appear in inserter. * - * @typedef {Object} Editor.InserterItem + * @typedef {Object} EditorInserterItem * @property {string} id Unique identifier for the item. * @property {string} name The type of block to create. * @property {Object} initialAttributes Attributes to pass to the newly created block. diff --git a/packages/block-library/src/columns/utils.js b/packages/block-library/src/columns/utils.js index a6773d469c98f7..33c77d2dace166 100644 --- a/packages/block-library/src/columns/utils.js +++ b/packages/block-library/src/columns/utils.js @@ -38,10 +38,10 @@ export const toWidthPrecision = ( value ) => * when the given block is the last block in the set. For the last block, the * behavior is reversed. * - * @param {WPBlock[]} blocks Block objects. - * @param {string} clientId Client ID to consider for adjacent blocks. + * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. + * @param {string} clientId Client ID to consider for adjacent blocks. * - * @return {WPBlock[]} Adjacent block objects. + * @return {import('@wordpress/blocks').WPBlockType[]} Adjacent block objects. */ export function getAdjacentBlocks( blocks, clientId ) { const index = findIndex( blocks, { clientId } ); @@ -54,8 +54,8 @@ export function getAdjacentBlocks( blocks, clientId ) { * Returns an effective width for a given block. An effective width is equal to * its attribute value if set, or a computed value assuming equal distribution. * - * @param {WPBlock} block Block object. - * @param {number} totalBlockCount Total number of blocks in Columns. + * @param {import('@wordpress/blocks').WPBlockType} block Block object. + * @param {number} totalBlockCount Total number of blocks in Columns. * * @return {number} Effective column width. */ @@ -67,9 +67,9 @@ export function getEffectiveColumnWidth( block, totalBlockCount ) { /** * Returns the total width occupied by the given set of column blocks. * - * @param {WPBlock[]} blocks Block objects. - * @param {?number} totalBlockCount Total number of blocks in Columns. - * Defaults to number of blocks passed. + * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. + * @param {?number} totalBlockCount Total number of blocks in Columns. + * Defaults to number of blocks passed. * * @return {number} Total width occupied by blocks. */ @@ -80,9 +80,9 @@ export function getTotalColumnsWidth( blocks, totalBlockCount = blocks.length ) /** * Returns an object of `clientId` → `width` of effective column widths. * - * @param {WPBlock[]} blocks Block objects. - * @param {?number} totalBlockCount Total number of blocks in Columns. - * Defaults to number of blocks passed. + * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. + * @param {?number} totalBlockCount Total number of blocks in Columns. + * Defaults to number of blocks passed. * * @return {Object} Column widths. */ @@ -98,10 +98,10 @@ export function getColumnWidths( blocks, totalBlockCount = blocks.length ) { * proportional to their current widths, constrained or expanded to fit within * the given available width. * - * @param {WPBlock[]} blocks Block objects. - * @param {number} availableWidth Maximum width to fit within. - * @param {?number} totalBlockCount Total number of blocks in Columns. - * Defaults to number of blocks passed. + * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. + * @param {number} availableWidth Maximum width to fit within. + * @param {?number} totalBlockCount Total number of blocks in Columns. + * Defaults to number of blocks passed. * * @return {Object} Redistributed column widths. */ @@ -120,7 +120,7 @@ export function getRedistributedColumnWidths( blocks, availableWidth, totalBlock * Returns true if column blocks within the provided set are assigned with * explicit widths, or false otherwise. * - * @param {WPBlock[]} blocks Block objects. + * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. * * @return {boolean} Whether columns have explicit widths. */ @@ -132,10 +132,10 @@ export function hasExplicitColumnWidths( blocks ) { * Returns a copy of the given set of blocks with new widths assigned from the * provided object of redistributed column widths. * - * @param {WPBlock[]} blocks Block objects. - * @param {Object} widths Redistributed column widths. + * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. + * @param {Object} widths Redistributed column widths. * - * @return {WPBlock[]} blocks Mapped block objects. + * @return {import('@wordpress/blocks').WPBlockType[]} blocks Mapped block objects. */ export function getMappedColumnWidths( blocks, widths ) { return blocks.map( ( block ) => merge( {}, block, { diff --git a/packages/blocks/README.md b/packages/blocks/README.md index 1af3f49adef88a..95832b946e97e6 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -517,7 +517,7 @@ which means the block is unmodified. _Parameters_ -- _block_ `WPBlock`: Block Object +- _block_ `null`: Block Object _Returns_ @@ -561,11 +561,11 @@ in the codebase. _Parameters_ -- _icon_ `WPBlockTypeIconRender`: Render behavior of a block type icon; one of a Dashicon slug, an element, or a component. +- _icon_ `null`: Render behavior of a block type icon; one of a Dashicon slug, an element, or a component. _Returns_ -- `WPBlockTypeIconDescriptor`: Object describing the icon. +- `null`: Object describing the icon. # **parse** @@ -645,7 +645,7 @@ _Parameters_ _Returns_ -- `?WPBlock`: The block, if it has been successfully registered; otherwise `undefined`. +- `?WPBlockType`: The block, if it has been successfully registered; otherwise `undefined`. # **serialize** @@ -750,7 +750,7 @@ _Parameters_ _Returns_ -- `?WPBlock`: The previous block value, if it has been successfully unregistered; otherwise `undefined`. +- `?WPBlockType`: The previous block value, if it has been successfully unregistered; otherwise `undefined`. # **updateCategory** @@ -768,7 +768,7 @@ wrapped component. _Returns_ -- `Component`: Enhanced component with injected BlockContent as prop. +- `null`: Enhanced component with injected BlockContent as prop. diff --git a/packages/blocks/src/api/children.js b/packages/blocks/src/api/children.js index 7cf70d2da78151..eff87d18466baa 100644 --- a/packages/blocks/src/api/children.js +++ b/packages/blocks/src/api/children.js @@ -16,7 +16,7 @@ import * as node from './node'; /** * A representation of a block's rich text value. * - * @typedef {WPBlockNode[]} WPBlockChildren + * @typedef {import('./node').WPBlockNode[]} WPBlockChildren */ /** @@ -24,7 +24,7 @@ import * as node from './node'; * * @param {WPBlockChildren} children Block children object to convert. * - * @return {WPElement} A serialize-capable element. + * @return {import('@wordpress/element').WPElement} A serialize-capable element. */ export function getSerializeCapableElement( children ) { // The fact that block children are compatible with the element serializer is @@ -41,7 +41,7 @@ export function getSerializeCapableElement( children ) { * * @param {WPBlockChildren} children Block children object to convert. * - * @return {Array} An array of individual block nodes. + * @return {Array} An array of individual block nodes. */ function getChildrenArray( children ) { // The fact that block children are compatible with the element serializer diff --git a/packages/blocks/src/api/parser.js b/packages/blocks/src/api/parser.js index 6300eac329f153..0b357e7f1272a7 100644 --- a/packages/blocks/src/api/parser.js +++ b/packages/blocks/src/api/parser.js @@ -296,11 +296,11 @@ export function getBlockAttributes( blockTypeOrName, innerHTML, attributes = {} * deprecated migrations applied, or the original block if it was both valid * and no eligible migrations exist. * - * @param {WPBlock} block Original block object. - * @param {Object} parsedAttributes Attributes as parsed from the initial - * block markup. + * @param {import('./registration').WPBlockType} block Original block object. + * @param {Object} parsedAttributes Attributes as parsed from the initial + * block markup. * - * @return {WPBlock} Migrated block object. + * @return {import('./registration').WPBlockType} Migrated block object. */ export function getMigratedBlock( block, parsedAttributes ) { const blockType = getBlockType( block.name ); diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index 024f9e9d55a3e3..b95f7bc8f3a668 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -28,7 +28,7 @@ import { DEPRECATED_ENTRY_KEYS } from './constants'; * Render behavior of a block type icon; one of a Dashicon slug, an element, * or a component. * - * @typedef {(string|WPElement|WPComponent)} WPBlockTypeIconRender + * @typedef {(string|import('@wordpress/element').WPElement|import('@wordpress/element').WPComponent)} WPBlockTypeIconRender * * @see https://developer.wordpress.org/resource/dashicons/ */ @@ -62,21 +62,21 @@ import { DEPRECATED_ENTRY_KEYS } from './constants'; * * @typedef {Object} WPBlockType * - * @property {string} name Block type's namespaced name. - * @property {string} title Human-readable block type label. - * @property {string} category Block type category classification, - * used in search interfaces to arrange - * block types by category. - * @property {WPBlockTypeIcon} [icon] Block type icon. - * @property {string[]} [keywords] Additional keywords to produce block - * type as result in search interfaces. - * @property {Object} [attributes] Block type attributes. - * @property {WPComponent} [save] Optional component describing - * serialized markup structure of a - * block type. - * @property {WPComponent} edit Component rendering an element to - * manipulate the attributes of a block - * in the context of an editor. + * @property {string} name Block type's namespaced name. + * @property {string} title Human-readable block type label. + * @property {string} category Block type category classification, + * used in search interfaces to arrange + * block types by category. + * @property {WPBlockTypeIcon} [icon] Block type icon. + * @property {string[]} [keywords] Additional keywords to produce block + * type as result in search interfaces. + * @property {Object} [attributes] Block type attributes. + * @property {import('@wordpress/element').WPComponent} [save] Optional component describing + * serialized markup structure of a + * block type. + * @property {import('@wordpress/element').WPComponent} edit Component rendering an element to + * manipulate the attributes of a block + * in the context of an editor. */ /** @@ -113,7 +113,7 @@ export function unstable__bootstrapServerSideBlockDefinitions( definitions ) { / * @param {string} name Block name. * @param {Object} settings Block settings. * - * @return {?WPBlock} The block, if it has been successfully registered; + * @return {?WPBlockType} The block, if it has been successfully registered; * otherwise `undefined`. */ export function registerBlockType( name, settings ) { @@ -233,7 +233,7 @@ export function registerBlockType( name, settings ) { * * @param {string} name Block name. * - * @return {?WPBlock} The previous block value, if it has been successfully + * @return {?WPBlockType} The previous block value, if it has been successfully * unregistered; otherwise `undefined`. */ export function unregisterBlockType( name ) { diff --git a/packages/blocks/src/api/serializer.js b/packages/blocks/src/api/serializer.js index 98b3928962a44b..a392fafd32d422 100644 --- a/packages/blocks/src/api/serializer.js +++ b/packages/blocks/src/api/serializer.js @@ -85,9 +85,9 @@ export function getSaveElement( blockTypeOrName, attributes, innerBlocks = [] ) /** * Filters the props applied to the block save result element. * - * @param {Object} props Props applied to save element. - * @param {WPBlockType} blockType Block type definition. - * @param {Object} attributes Block attributes. + * @param {Object} props Props applied to save element. + * @param {import('./registration').WPBlockType} blockType Block type definition. + * @param {Object} attributes Block attributes. */ const props = applyFilters( 'blocks.getSaveContent.extraProps', @@ -104,9 +104,9 @@ export function getSaveElement( blockTypeOrName, attributes, innerBlocks = [] ) /** * Filters the save result of a block during serialization. * - * @param {WPElement} element Block save result. - * @param {WPBlockType} blockType Block type definition. - * @param {Object} attributes Block attributes. + * @param {import('@wordpress/element').WPElement} element Block save result. + * @param {import('./registration').WPBlockType} blockType Block type definition. + * @param {Object} attributes Block attributes. */ element = applyFilters( 'blocks.getSaveElement', element, blockType, attributes ); diff --git a/packages/blocks/src/api/utils.js b/packages/blocks/src/api/utils.js index 99dc98b5c3204b..5d66227aa2d239 100644 --- a/packages/blocks/src/api/utils.js +++ b/packages/blocks/src/api/utils.js @@ -28,7 +28,7 @@ const ICON_COLORS = [ '#191e23', '#f8f9f9' ]; * and its attributes are equal to the default attributes * which means the block is unmodified. * - * @param {WPBlock} block Block Object + * @param {import('./registration').WPBlockType} block Block Object * * @return {boolean} Whether the block is an unmodified default block */ @@ -77,11 +77,11 @@ export function isValidIcon( icon ) { * and returns a new icon object that is normalized so we can rely on just on possible icon structure * in the codebase. * - * @param {WPBlockTypeIconRender} icon Render behavior of a block type icon; - * one of a Dashicon slug, an element, or a - * component. + * @param {import('./registration').WPBlockTypeIconRender} icon Render behavior of a block type icon; + * one of a Dashicon slug, an element, or a + * component. * - * @return {WPBlockTypeIconDescriptor} Object describing the icon. + * @return {import('./registration').WPBlockTypeIconDescriptor} Object describing the icon. */ export function normalizeIconObject( icon ) { if ( isValidIcon( icon ) ) { diff --git a/packages/blocks/src/block-content-provider/index.js b/packages/blocks/src/block-content-provider/index.js index 352550a87be80f..e9343ad08d63aa 100644 --- a/packages/blocks/src/block-content-provider/index.js +++ b/packages/blocks/src/block-content-provider/index.js @@ -26,7 +26,7 @@ const { Consumer, Provider } = createContext( () => {} ); * * ``` * - * @return {WPElement} Element with BlockContent injected via context. + * @return {import('@wordpress/element').WPComponent} Element with BlockContent injected via context. */ const BlockContentProvider = ( { children, innerBlocks } ) => { const BlockContent = () => { @@ -48,7 +48,7 @@ const BlockContentProvider = ( { children, innerBlocks } ) => { * A Higher Order Component used to inject BlockContent using context to the * wrapped component. * - * @return {Component} Enhanced component with injected BlockContent as prop. + * @return {import('@wordpress/element').WPComponent} Enhanced component with injected BlockContent as prop. */ export const withBlockContentContext = createHigherOrderComponent( ( OriginalComponent ) => { return ( props ) => ( diff --git a/packages/components/src/autocomplete/index.js b/packages/components/src/autocomplete/index.js index 283ccd92633b04..34c0ed239df878 100644 --- a/packages/components/src/autocomplete/index.js +++ b/packages/components/src/autocomplete/index.js @@ -77,7 +77,7 @@ import withSpokenMessages from '../higher-order/with-spoken-messages'; /** * A completion value. * - * @typedef {(string|WPElement|Object)} OptionCompletionValue + * @typedef {(string|import('@wordpress/element').WPElement|Object)} OptionCompletionValue */ /** diff --git a/packages/components/src/date-time/date.js b/packages/components/src/date-time/date.js index 7361494a61e688..19c701ffbf74a9 100644 --- a/packages/components/src/date-time/date.js +++ b/packages/components/src/date-time/date.js @@ -65,7 +65,7 @@ class DatePicker extends Component { * object representing now. If a null value is passed, return a null value. * * @param {?string} currentDate Date representing the currently selected date or null to signify no selection. - * @return {?Moment} Moment object for selected date or null. + * @return {?import('moment').Moment} Moment object for selected date or null. */ getMomentDate( currentDate ) { if ( null === currentDate ) { diff --git a/packages/components/src/higher-order/with-focus-return/index.js b/packages/components/src/higher-order/with-focus-return/index.js index 2b504878bdf528..f193b348b99010 100644 --- a/packages/components/src/higher-order/with-focus-return/index.js +++ b/packages/components/src/higher-order/with-focus-return/index.js @@ -35,12 +35,12 @@ function isComponentLike( object ) { * reference to the current active element so we know where to restore focus * when the component is unmounted. * - * @param {(WPComponent|Object)} options The component to be enhanced with - * focus return behavior, or an object - * describing the component and the - * focus return characteristics. + * @param {(import('@wordpress/element').WPComponent|Object)} options The component to be enhanced with + * focus return behavior, or an object + * describing the component and the + * focus return characteristics. * - * @return {Component} Component with the focus restauration behaviour. + * @return {import('@wordpress/element').WPComponent} Component with the focus restauration behaviour. */ function withFocusReturn( options ) { // Normalize as overloaded form `withFocusReturn( options )( Component )` diff --git a/packages/components/src/higher-order/with-notices/index.js b/packages/components/src/higher-order/with-notices/index.js index 49a44608039ce1..aa5710baad7623 100644 --- a/packages/components/src/higher-order/with-notices/index.js +++ b/packages/components/src/higher-order/with-notices/index.js @@ -17,8 +17,9 @@ import NoticeList from '../../notice/list'; /** * Override the default edit UI to include notices if supported. * - * @param {Function|Component} OriginalComponent Original component. - * @return {Component} Wrapped component. + * @param {import('@wordpress/element').WPComponent} OriginalComponent Original component. + * + * @return {import('@wordpress/element').WPComponent} Wrapped component. */ export default createHigherOrderComponent( ( OriginalComponent ) => { return class WrappedBlockEdit extends Component { diff --git a/packages/components/src/higher-order/with-spoken-messages/index.js b/packages/components/src/higher-order/with-spoken-messages/index.js index de17dc62aeb575..389e4c2cffcfa4 100644 --- a/packages/components/src/higher-order/with-spoken-messages/index.js +++ b/packages/components/src/higher-order/with-spoken-messages/index.js @@ -14,9 +14,9 @@ import { createHigherOrderComponent } from '@wordpress/compose'; * A Higher Order Component used to be provide a unique instance ID by * component. * - * @param {WPElement} WrappedComponent The wrapped component. + * @param {import('@wordpress/element').WPComponent} WrappedComponent The wrapped component. * - * @return {Component} Component with an instanceId prop. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ export default createHigherOrderComponent( ( WrappedComponent ) => { return class extends Component { diff --git a/packages/components/src/menu-item/index.js b/packages/components/src/menu-item/index.js index b7cc7c8ca7a0bd..76ffa2e5ad1895 100644 --- a/packages/components/src/menu-item/index.js +++ b/packages/components/src/menu-item/index.js @@ -18,7 +18,7 @@ import IconButton from '../icon-button'; /** * Renders a generic menu item for use inside the more menu. * - * @return {WPElement} More menu item. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ export function MenuItem( { children, diff --git a/packages/components/src/modal/frame.js b/packages/components/src/modal/frame.js index 286171a06e0ca2..95cd509eb3ed26 100644 --- a/packages/components/src/modal/frame.js +++ b/packages/components/src/modal/frame.js @@ -101,7 +101,7 @@ class ModalFrame extends Component { /** * Renders the modal frame element. * - * @return {WPElement} The modal frame element. + * @return {import('@wordpress/element').WPElement} The modal frame element. */ render() { const { diff --git a/packages/components/src/modal/index.js b/packages/components/src/modal/index.js index f4a64c289b4e7d..dd8b0bef8f19ef 100644 --- a/packages/components/src/modal/index.js +++ b/packages/components/src/modal/index.js @@ -98,7 +98,7 @@ class Modal extends Component { /** * Renders the modal. * - * @return {WPElement} The modal element. + * @return {import('@wordpress/element').WPElement} The modal element. */ render() { const { diff --git a/packages/components/src/placeholder/README.md b/packages/components/src/placeholder/README.md index 2a12363e7fde01..9e5bf053417d0d 100644 --- a/packages/components/src/placeholder/README.md +++ b/packages/components/src/placeholder/README.md @@ -16,7 +16,7 @@ const MyPlaceholder = () => ( Name | Type | Default | Description --- | --- | --- | --- -`icon` | `string, ReactElement` | `undefined` | If provided, renders an icon next to the label. +`icon` | `string, WPElement` | `undefined` | If provided, renders an icon next to the label. `label` | `string` | `undefined` | Renders a label for the placeholder. `instructions` | `string` | `undefined` | Renders instruction text below label. `isColumnLayout` | `bool` | `false` | Changes placeholder children layout from flex-row to flex-column. diff --git a/packages/components/src/scroll-lock/index.js b/packages/components/src/scroll-lock/index.js index 0d600aac62f14d..07e62cb18a5227 100644 --- a/packages/components/src/scroll-lock/index.js +++ b/packages/components/src/scroll-lock/index.js @@ -12,7 +12,7 @@ import { Component } from '@wordpress/element'; * @param {Object} args Keyword args. * @param {HTMLDocument} args.htmlDocument The document to lock the scroll for. * @param {string} args.className The name of the class used to lock scrolling. - * @return {Component} The bound ScrollLock component. + * @return {import('@wordpress/element').WPComponent} The bound ScrollLock component. */ export function createScrollLockComponent( { htmlDocument = document, diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js index ca41d32bb6e1b9..8a795f98e2b5bf 100644 --- a/packages/components/src/toolbar/index.js +++ b/packages/components/src/toolbar/index.js @@ -36,11 +36,11 @@ import ToolbarContainer from './toolbar-container'; * * @param {Object} props * @param {Array} [props.controls] The controls to render in this toolbar. - * @param {ReactElement} [props.children] Any other things to render inside the + * @param {import('@wordpress/element').WPElement} [props.children] Any other things to render inside the * toolbar besides the controls. * @param {string} [props.className] Class to set on the container div. * - * @return {ReactElement} The rendered toolbar. + * @return {import('@wordpress/element').WPComponent} The rendered component. */ function Toolbar( { controls = [], children, className, isCollapsed, icon, label, ...otherProps } ) { if ( diff --git a/packages/compose/README.md b/packages/compose/README.md index dc47f26e995652..9c69fed546567a 100644 --- a/packages/compose/README.md +++ b/packages/compose/README.md @@ -90,7 +90,7 @@ _Parameters_ _Returns_ -- `WPComponent`: Component class with generated display name assigned. +- `null`: Component class with generated display name assigned. # **ifCondition** @@ -117,7 +117,7 @@ _Parameters_ _Returns_ -- `WPComponent`: Component class with generated display name assigned. +- `null`: Component class with generated display name assigned. # **useMediaQuery** @@ -163,11 +163,11 @@ component. _Parameters_ -- _WrappedComponent_ `WPElement`: The wrapped component. +- _WrappedComponent_ `null`: The wrapped component. _Returns_ -- `Component`: Component with an instanceId prop. +- `null`: Component with an instanceId prop. # **withSafeTimeout** @@ -176,11 +176,11 @@ that ought to be bound to a component's lifecycle. _Parameters_ -- _OriginalComponent_ `Component`: Component requiring setTimeout +- _OriginalComponent_ `null`: Component requiring setTimeout _Returns_ -- `Component`: Wrapped component. +- `null`: Wrapped component. # **withState** @@ -193,7 +193,7 @@ _Parameters_ _Returns_ -- `Component`: Wrapped component. +- `null`: Wrapped component. diff --git a/packages/compose/src/higher-order/pure/index.js b/packages/compose/src/higher-order/pure/index.js index e721fbb7964796..d9551f5582e2ad 100644 --- a/packages/compose/src/higher-order/pure/index.js +++ b/packages/compose/src/higher-order/pure/index.js @@ -18,7 +18,7 @@ import createHigherOrderComponent from '../../utils/create-higher-order-componen * @param {string} modifierName Seed name from which to * generated display name. * - * @return {WPComponent} Component class with generated display name assigned. + * @return {import('@wordpress/element').WPComponent} Component class with generated display name assigned. */ const pure = createHigherOrderComponent( ( Wrapped ) => { if ( Wrapped.prototype instanceof Component ) { diff --git a/packages/compose/src/higher-order/with-instance-id/index.js b/packages/compose/src/higher-order/with-instance-id/index.js index 53c09ec56f8882..cb8cbfb42ecf49 100644 --- a/packages/compose/src/higher-order/with-instance-id/index.js +++ b/packages/compose/src/higher-order/with-instance-id/index.js @@ -12,9 +12,9 @@ import createHigherOrderComponent from '../../utils/create-higher-order-componen * A Higher Order Component used to be provide a unique instance ID by * component. * - * @param {WPElement} WrappedComponent The wrapped component. + * @param {import('@wordpress/element').WPComponent} WrappedComponent The wrapped component. * - * @return {Component} Component with an instanceId prop. + * @return {import('@wordpress/element').WPComponent} Component with an instanceId prop. */ export default createHigherOrderComponent( ( WrappedComponent ) => { let instances = 0; diff --git a/packages/compose/src/higher-order/with-safe-timeout/index.js b/packages/compose/src/higher-order/with-safe-timeout/index.js index 910dd94fddc19d..5a0b1cfec3a574 100644 --- a/packages/compose/src/higher-order/with-safe-timeout/index.js +++ b/packages/compose/src/higher-order/with-safe-timeout/index.js @@ -17,9 +17,9 @@ import createHigherOrderComponent from '../../utils/create-higher-order-componen * A higher-order component used to provide and manage delayed function calls * that ought to be bound to a component's lifecycle. * - * @param {Component} OriginalComponent Component requiring setTimeout + * @param {import('@wordpress/element').WPComponent} OriginalComponent Component requiring setTimeout * - * @return {Component} Wrapped component. + * @return {import('@wordpress/element').WPComponent} Wrapped component. */ const withSafeTimeout = createHigherOrderComponent( ( OriginalComponent ) => { diff --git a/packages/compose/src/higher-order/with-state/index.js b/packages/compose/src/higher-order/with-state/index.js index 19e639043bd28b..7f59410853ac64 100644 --- a/packages/compose/src/higher-order/with-state/index.js +++ b/packages/compose/src/higher-order/with-state/index.js @@ -14,7 +14,7 @@ import createHigherOrderComponent from '../../utils/create-higher-order-componen * * @param {?Object} initialState Optional initial state of the component. * - * @return {Component} Wrapped component. + * @return {import('@wordpress/element').WPComponent} Wrapped component. */ export default function withState( initialState = {} ) { return createHigherOrderComponent( ( OriginalComponent ) => { diff --git a/packages/compose/src/utils/create-higher-order-component/index.js b/packages/compose/src/utils/create-higher-order-component/index.js index 448193468c94eb..4bac128095b936 100644 --- a/packages/compose/src/utils/create-higher-order-component/index.js +++ b/packages/compose/src/utils/create-higher-order-component/index.js @@ -12,7 +12,7 @@ import { camelCase, upperFirst } from 'lodash'; * @param {string} modifierName Seed name from which to * generated display name. * - * @return {WPComponent} Component class with generated display name assigned. + * @return {import('@wordpress/element').WPComponent} Component class with generated display name assigned. */ function createHigherOrderComponent( mapComponentToEnhancedComponent, modifierName ) { return ( OriginalComponent ) => { diff --git a/packages/core-data/README.md b/packages/core-data/README.md index 892a6e572a99be..a2bb3ccbe6deeb 100644 --- a/packages/core-data/README.md +++ b/packages/core-data/README.md @@ -106,7 +106,7 @@ a given URl has been received. _Parameters_ - _url_ `string`: URL to preview the embed for. -- _preview_ `Mixed`: Preview data. +- _preview_ `*`: Preview data. _Returns_ diff --git a/packages/core-data/src/actions.js b/packages/core-data/src/actions.js index dc77d54994ac0b..a79aaba7e33d8f 100644 --- a/packages/core-data/src/actions.js +++ b/packages/core-data/src/actions.js @@ -109,8 +109,8 @@ export function receiveThemeSupports( themeSupports ) { * Returns an action object used in signalling that the preview data for * a given URl has been received. * - * @param {string} url URL to preview the embed for. - * @param {Mixed} preview Preview data. + * @param {string} url URL to preview the embed for. + * @param {*} preview Preview data. * * @return {Object} Action object. */ diff --git a/packages/data/README.md b/packages/data/README.md index a76019371e725a..e3f3d9d50e50e1 100644 --- a/packages/data/README.md +++ b/packages/data/README.md @@ -693,7 +693,7 @@ _Parameters_ _Returns_ -- `Component`: Enhanced component with merged dispatcher props. +- `null`: Enhanced component with merged dispatcher props. # **withRegistry** @@ -702,11 +702,11 @@ registry context passed as its `registry` prop. _Parameters_ -- _OriginalComponent_ `WPComponent`: Original component. +- _OriginalComponent_ `null`: Original component. _Returns_ -- `WPComponent`: Enhanced component. +- `null`: Enhanced component. # **withSelect** @@ -750,7 +750,7 @@ _Parameters_ _Returns_ -- `Component`: Enhanced component with merged state data props. +- `null`: Enhanced component with merged state data props. diff --git a/packages/data/src/components/with-dispatch/index.js b/packages/data/src/components/with-dispatch/index.js index 2247a253a189d5..9f613c7b9d0f54 100644 --- a/packages/data/src/components/with-dispatch/index.js +++ b/packages/data/src/components/with-dispatch/index.js @@ -85,7 +85,7 @@ import { useDispatchWithMap } from '../use-dispatch'; * returns an object with the same keys. For example, it should not contain * conditions under which a different value would be returned. * - * @return {Component} Enhanced component with merged dispatcher props. + * @return {import('@wordpress/element').WPComponent} Enhanced component with merged dispatcher props. */ const withDispatch = ( mapDispatchToProps ) => createHigherOrderComponent( ( WrappedComponent ) => ( ownProps ) => { diff --git a/packages/data/src/components/with-registry/index.js b/packages/data/src/components/with-registry/index.js index 32d1c8e1a40fd5..b27c1d278ad242 100644 --- a/packages/data/src/components/with-registry/index.js +++ b/packages/data/src/components/with-registry/index.js @@ -12,9 +12,9 @@ import { RegistryConsumer } from '../registry-provider'; * Higher-order component which renders the original component with the current * registry context passed as its `registry` prop. * - * @param {WPComponent} OriginalComponent Original component. + * @param {import('@wordpress/element').WPComponent} OriginalComponent Original component. * - * @return {WPComponent} Enhanced component. + * @return {import('@wordpress/element').WPComponent} Enhanced component. */ const withRegistry = createHigherOrderComponent( ( OriginalComponent ) => ( props ) => ( diff --git a/packages/data/src/components/with-select/index.js b/packages/data/src/components/with-select/index.js index f9659e7e865a8f..feee44ea313c9a 100644 --- a/packages/data/src/components/with-select/index.js +++ b/packages/data/src/components/with-select/index.js @@ -45,7 +45,7 @@ import useSelect from '../use-select'; * component and update automatically if the price of a hammer ever changes in * the store. * - * @return {Component} Enhanced component with merged state data props. + * @return {import('@wordpress/element').WPComponent} Enhanced component with merged state data props. */ const withSelect = ( mapSelectToProps ) => createHigherOrderComponent( ( WrappedComponent ) => pure( diff --git a/packages/data/src/factory.js b/packages/data/src/factory.js index 2a10c7a8e7afc1..e6e867fecdcb8d 100644 --- a/packages/data/src/factory.js +++ b/packages/data/src/factory.js @@ -29,7 +29,7 @@ export function createRegistrySelector( registrySelector ) { * Registry on which to call `select`, stubbed for non-standard usage to * use the default registry. * - * @type {WPDataRegistry} + * @type {import('./registry').WPDataRegistry} */ selector.registry = defaultRegistry; diff --git a/packages/data/src/namespace-store/index.js b/packages/data/src/namespace-store/index.js index b3bd639fcddfa3..3953a753928590 100644 --- a/packages/data/src/namespace-store/index.js +++ b/packages/data/src/namespace-store/index.js @@ -30,11 +30,11 @@ import * as metadataActions from './metadata/actions'; /** * Creates a namespace object with a store derived from the reducer given. * - * @param {string} key Unique namespace identifier. - * @param {Object} options Registered store options, with properties - * describing reducer, actions, selectors, and - * resolvers. - * @param {WPDataRegistry} registry Registry reference. + * @param {string} key Unique namespace identifier. + * @param {Object} options Registered store options, with properties + * describing reducer, actions, selectors, and + * resolvers. + * @param {import('../registry').WPDataRegistry} registry Registry reference. * * @return {Object} Store Object. */ @@ -104,11 +104,11 @@ export default function createNamespace( key, options, registry ) { /** * Creates a redux store for a namespace. * - * @param {string} key Unique namespace identifier. - * @param {Object} options Registered store options, with properties - * describing reducer, actions, selectors, and - * resolvers. - * @param {WPDataRegistry} registry Registry reference. + * @param {string} key Unique namespace identifier. + * @param {Object} options Registered store options, with properties + * describing reducer, actions, selectors, and + * resolvers. + * @param {import('../registry').WPDataRegistry} registry Registry reference. * * @return {Object} Newly created redux store. */ diff --git a/packages/data/src/plugins/persistence/index.js b/packages/data/src/plugins/persistence/index.js index 871a7e56133594..e5461a4204d724 100644 --- a/packages/data/src/plugins/persistence/index.js +++ b/packages/data/src/plugins/persistence/index.js @@ -112,10 +112,10 @@ export function createPersistenceInterface( options ) { /** * Data plugin to persist store state into a single storage key. * - * @param {WPDataRegistry} registry Data registry. - * @param {?WPDataPersistencePluginOptions} pluginOptions Plugin options. + * @param {import('../../registry').WPDataRegistry} registry Data registry. + * @param {?WPDataPersistencePluginOptions} pluginOptions Plugin options. * - * @return {WPDataPlugin} Data plugin. + * @return {import('../../registry').WPDataPlugin} Data plugin. */ const persistencePlugin = function( registry, pluginOptions ) { const persistence = createPersistenceInterface( pluginOptions ); diff --git a/packages/data/src/resolvers-cache-middleware.js b/packages/data/src/resolvers-cache-middleware.js index e7e0a2ae7c6201..0783f264c91423 100644 --- a/packages/data/src/resolvers-cache-middleware.js +++ b/packages/data/src/resolvers-cache-middleware.js @@ -6,10 +6,10 @@ import { get } from 'lodash'; /** * Creates a middleware handling resolvers cache invalidation. * - * @param {WPDataRegistry} registry The registry reference for which to create - * the middleware. - * @param {string} reducerKey The namespace for which to create the - * middleware. + * @param {import('./registry').WPDataRegistry} registry The registry reference for which to create + * the middleware. + * @param {string} reducerKey The namespace for which to create the + * middleware. * * @return {Function} Middleware function. */ diff --git a/packages/date/README.md b/packages/date/README.md index c4bad6ef1636e1..8ee9d3fdf0a74d 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|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `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|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `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|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `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|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `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 39b4425ea2da22..560fd5605ba9d8 100644 --- a/packages/date/src/index.js +++ b/packages/date/src/index.js @@ -145,7 +145,7 @@ const formatMap = { /** * Gets the ordinal suffix. * - * @param {moment} momentDate Moment instance. + * @param {import('moment').Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -160,7 +160,7 @@ const formatMap = { /** * Gets the day of the year (zero-indexed). * - * @param {moment} momentDate Moment instance. + * @param {import('moment').Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -180,7 +180,7 @@ const formatMap = { /** * Gets the days in the month. * - * @param {moment} momentDate Moment instance. + * @param {import('moment').Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -192,7 +192,7 @@ const formatMap = { /** * Gets whether the current year is a leap year. * - * @param {moment} momentDate Moment instance. + * @param {import('moment').Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -209,7 +209,7 @@ const formatMap = { /** * Gets the current time in Swatch Internet Time (.beats). * - * @param {moment} momentDate Moment instance. + * @param {import('moment').Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -240,7 +240,7 @@ const formatMap = { /** * Gets whether the timezone is in DST currently. * - * @param {moment} momentDate Moment instance. + * @param {import('moment').Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -253,7 +253,7 @@ const formatMap = { /** * Gets the timezone offset in seconds. * - * @param {moment} momentDate Moment instance. + * @param {import('moment').Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -273,10 +273,10 @@ const formatMap = { /** * Formats a date. Does not alter the date's timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. - * @param {(Date|string|moment|null)} dateValue Date object or string, - * parsable by moment.js. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|import('moment').Moment|null)} dateValue Date object or string, + * parsable by moment.js. * * @return {string} Formatted date. */ @@ -314,10 +314,10 @@ export function format( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `date()` in PHP), in the site's timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. - * @param {(Date|string|moment|null)} dateValue Date object or string, - * parsable by moment.js. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|import('moment').Moment|null)} dateValue Date object or string, + * parsable by moment.js. * * @return {string} Formatted date. */ @@ -330,10 +330,10 @@ export function date( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `date()` in PHP), in the UTC timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. - * @param {(Date|string|moment|null)} dateValue Date object or string, - * parsable by moment.js. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|import('moment').Moment|null)} dateValue Date object or string, + * parsable by moment.js. * * @return {string} Formatted date. */ @@ -345,12 +345,12 @@ export function gmdate( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `date_i18n()` in PHP). * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. - * @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. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|import('moment').Moment|null)} dateValue Date object or string, + * parsable by moment.js. + * @param {boolean} gmt True for GMT/UTC, false for + * site's timezone. * * @return {string} Formatted date. */ diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md index d8b3263c2e6e99..a90533b68ae703 100644 --- a/packages/e2e-test-utils/README.md +++ b/packages/e2e-test-utils/README.md @@ -191,7 +191,7 @@ _Parameters_ _Returns_ -- `?ElementHandle`: Object that represents an in-page DOM element. +- `null`: Object that represents an in-page DOM element. # **findSidebarPanelWithTitle** @@ -203,7 +203,7 @@ _Parameters_ _Returns_ -- `?ElementHandle`: Object that represents an in-page DOM element. +- `null`: Object that represents an in-page DOM element. # **getAllBlockInserterItemTitles** @@ -529,7 +529,7 @@ without the new dimensions being applied. _Parameters_ - _width_ `number`: Width of the window. -- _height_ `height`: Height of the window. +- _height_ `number`: Height of the window. 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..598995828661c4 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,7 @@ /** * Callback which automatically accepts dialog. * - * @param {puppeteer.Dialog} dialog Dialog object dispatched by page via the 'dialog' event. + * @param {import('puppeteer').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 a4167fe6e2e6cd..f4a5f2f8a98744 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 @@ -8,7 +8,7 @@ import { first } from 'lodash'; * * @param {string} panelTitle The name of sidebar panel. * - * @return {?ElementHandle} Object that represents an in-page DOM element. + * @return {?import('puppeteer').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 ff60dca5f00782..4bd283be731db8 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 @@ -8,7 +8,7 @@ import { first } from 'lodash'; * * @param {string} panelTitle The name of sidebar panel. * - * @return {?ElementHandle} Object that represents an in-page DOM element. + * @return {?import('puppeteer').ElementHandle} Object that represents an in-page DOM element. */ export async function findSidebarPanelWithTitle( panelTitle ) { const classSelect = ( className ) => `[contains(concat(" ", @class, " "), " ${ className } ")]`; diff --git a/packages/e2e-test-utils/src/wait-for-window-dimensions.js b/packages/e2e-test-utils/src/wait-for-window-dimensions.js index 9b505cf3b12807..924a5c939b3da0 100644 --- a/packages/e2e-test-utils/src/wait-for-window-dimensions.js +++ b/packages/e2e-test-utils/src/wait-for-window-dimensions.js @@ -5,7 +5,7 @@ * https://github.com/GoogleChrome/puppeteer/issues/1751 * * @param {number} width Width of the window. - * @param {height} height Height of the window. + * @param {number} height Height of the window. */ export async function waitForWindowDimensions( width, height ) { await page 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 56e5976513746d..877d1c0dd04aed 100644 --- a/packages/e2e-tests/specs/editor/various/adding-blocks.test.js +++ b/packages/e2e-tests/specs/editor/various/adding-blocks.test.js @@ -17,7 +17,7 @@ describe( 'adding blocks', () => { /** * Given a Puppeteer ElementHandle, clicks below its bounding box. * - * @param {Puppeteer.ElementHandle} elementHandle Element handle. + * @param {import('puppeteer').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 505f8cca3ba3a4..d460b7a0cd8f1f 100644 --- a/packages/e2e-tests/specs/editor/various/preview.test.js +++ b/packages/e2e-tests/specs/editor/various/preview.test.js @@ -41,7 +41,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 {import('puppeteer').Page} previewPage Page on which to await navigation. * * @return {Promise} Promise resolving once navigation completes. */ diff --git a/packages/edit-post/README.md b/packages/edit-post/README.md index 3b7b01a53e6dd3..b6c2e914f8b758 100644 --- a/packages/edit-post/README.md +++ b/packages/edit-post/README.md @@ -92,13 +92,13 @@ _Parameters_ - _props_ `Object`: Component props. - _props.allowedBlocks_ `[Array]`: An array containing a list of block names for which the item should be shown. If not present, it'll be rendered for any block. If multiple blocks are selected, it'll be shown if and only if all of them are in the whitelist. -- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. +- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. - _props.label_ `string`: The menu item text. - _props.onClick_ `Function`: Callback function to be executed when the user click the menu item. _Returns_ -- `WPElement`: The WPElement to be rendered. +- `null`: The component to be rendered. # **PluginDocumentSettingPanel** @@ -149,11 +149,11 @@ _Parameters_ - _props.name_ `[string]`: The machine-friendly name for the panel. - _props.className_ `[string]`: An optional class name added to the row. - _props.title_ `[string]`: The title of the panel -- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. +- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. _Returns_ -- `WPElement`: The WPElement to be rendered. +- `null`: The component to be rendered. # **PluginMoreMenuItem** @@ -206,13 +206,13 @@ _Parameters_ - _props_ `Object`: Component properties. - _props.href_ `[string]`: When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. -- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. +- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. - _props.onClick_ `[Function]`: The callback function to be executed when the user clicks the menu item. - _props.other_ `[...*]`: Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. _Returns_ -- `WPElement`: The element to be rendered. +- `null`: The component to be rendered. # **PluginPostPublishPanel** @@ -261,11 +261,11 @@ _Parameters_ - _props.className_ `[string]`: An optional class name added to the panel. - _props.title_ `[string]`: Title displayed at the top of the panel. - _props.initialOpen_ `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. -- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. +- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. _Returns_ -- `WPElement`: The WPElement to be rendered. +- `null`: The component to be rendered. # **PluginPostStatusInfo** @@ -312,7 +312,7 @@ _Parameters_ _Returns_ -- `WPElement`: The WPElement to be rendered. +- `null`: The component to be rendered. # **PluginPrePublishPanel** @@ -361,11 +361,11 @@ _Parameters_ - _props.className_ `[string]`: An optional class name added to the panel. - _props.title_ `[string]`: Title displayed at the top of the panel. - _props.initialOpen_ `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. -- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. +- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. _Returns_ -- `WPElement`: The WPElement to be rendered. +- `null`: The component to be rendered. # **PluginSidebar** @@ -432,11 +432,11 @@ _Parameters_ - _props.className_ `[string]`: An optional class name added to the sidebar body. - _props.title_ `string`: Title displayed at the top of the sidebar. - _props.isPinnable_ `[boolean]`: Whether to allow to pin sidebar to toolbar. -- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. +- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. _Returns_ -- `WPElement`: Plugin sidebar component. +- `null`: Plugin sidebar component. # **PluginSidebarMoreMenuItem** @@ -482,11 +482,11 @@ _Parameters_ - _props_ `Object`: Component props. - _props.target_ `string`: A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. -- _props.icon_ `[(string|Element)]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. +- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. _Returns_ -- `WPElement`: The element to be rendered. +- `null`: The component to be rendered. # **reinitializeEditor** diff --git a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js index 8503692c289b07..881034393fd389 100644 --- a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js +++ b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js @@ -35,7 +35,7 @@ const shouldRenderItem = ( selectedBlocks, allowedBlocks ) => ! Array.isArray( a * * @param {Object} props Component props. * @param {Array} [props.allowedBlocks] An array containing a list of block names for which the item should be shown. If not present, it'll be rendered for any block. If multiple blocks are selected, it'll be shown if and only if all of them are in the whitelist. - * @param {string|Element} [props.icon] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. + * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. * @param {string} props.label The menu item text. * @param {Function} props.onClick Callback function to be executed when the user click the menu item. * @@ -81,7 +81,7 @@ const shouldRenderItem = ( selectedBlocks, allowedBlocks ) => ! Array.isArray( a * ); * ``` * - * @return {WPElement} The WPElement to be rendered. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ const PluginBlockSettingsMenuItem = ( { allowedBlocks, icon, label, onClick, small, role } ) => ( diff --git a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js index e29ec22e90a208..9597af6c328e5f 100644 --- a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js @@ -32,7 +32,7 @@ const PluginMoreMenuItem = ( { onClick = noop, ...props } ) => ( * * @param {Object} props Component properties. * @param {string} [props.href] When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. - * @param {string|Element} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. + * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. * @param {Function} [props.onClick=noop] The callback function to be executed when the user clicks the menu item. * @param {...*} [props.other] Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. * @@ -78,7 +78,7 @@ const PluginMoreMenuItem = ( { onClick = noop, ...props } ) => ( * ); * ``` * - * @return {WPElement} The element to be rendered. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ export default compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js index e1849f2e7890ed..ea0167b4ce2307 100644 --- a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js @@ -28,7 +28,7 @@ const PluginSidebarMoreMenuItem = ( { children, icon, isSelected, onClick } ) => * * @param {Object} props Component props. * @param {string} props.target A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. - * @param {string|Element} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. + * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. * * @example ES5 * ```js @@ -64,7 +64,7 @@ const PluginSidebarMoreMenuItem = ( { children, icon, isSelected, onClick } ) => * ); * ``` * - * @return {WPElement} The element to be rendered. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ export default compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js index ef10b4ed77ef30..bdc118376efa05 100644 --- a/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js @@ -48,7 +48,7 @@ const PluginDocumentSettingFill = ( { isEnabled, panelName, opened, onToggle, cl * @param {string} [props.name] The machine-friendly name for the panel. * @param {string} [props.className] An optional class name added to the row. * @param {string} [props.title] The title of the panel - * @param {string|Element} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. + * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example ES5 * ```js @@ -89,7 +89,7 @@ const PluginDocumentSettingFill = ( { isEnabled, panelName, opened, onToggle, cl * registerPlugin( 'document-setting-test', { render: MyDocumentSettingTest } ); * ``` * - * @return {WPElement} The WPElement to be rendered. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ const PluginDocumentSettingPanel = compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js index a84124905d7d46..e050d1f0df8505 100644 --- a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js @@ -27,7 +27,7 @@ const PluginPostPublishPanelFill = ( { children, className, title, initialOpen = * @param {string} [props.className] An optional class name added to the panel. * @param {string} [props.title] Title displayed at the top of the panel. * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. When no title is provided it is always opened. - * @param {string|Element} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. + * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example ES5 * ```js @@ -65,7 +65,7 @@ const PluginPostPublishPanelFill = ( { children, className, title, initialOpen = * ); * ``` * - * @return {WPElement} The WPElement to be rendered. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ const PluginPostPublishPanel = compose( diff --git a/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js b/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js index e099fa232e84f6..cbedd5f7c88c8f 100644 --- a/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js @@ -49,7 +49,7 @@ export const { Fill, Slot } = createSlotFill( 'PluginPostStatusInfo' ); * ); * ``` * - * @return {WPElement} The WPElement to be rendered. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ const PluginPostStatusInfo = ( { children, className } ) => ( diff --git a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js index 4a3b02fba2803b..54d6f1c944b442 100644 --- a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js @@ -18,16 +18,19 @@ const PluginPrePublishPanelFill = ( { children, className, title, initialOpen = ); + /** * Renders provided content to the pre-publish side panel in the publish flow * (side panel that opens when a user first pushes "Publish" from the main editor). * - * @param {Object} props Component props. - * @param {string} [props.className] An optional class name added to the panel. - * @param {string} [props.title] Title displayed at the top of the panel. - * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. When no title is provided it is always opened. - * @param {string|Element} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. - + * @param {Object} props Component props. + * @param {string} [props.className] An optional class name added to the panel. + * @param {string} [props.title] Title displayed at the top of the panel. + * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. + * When no title is provided it is always opened. + * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) + * icon slug string, or an SVG WP element, to be rendered when + * the sidebar is pinned to toolbar. * * @example ES5 * ```js @@ -65,7 +68,7 @@ const PluginPrePublishPanelFill = ( { children, className, title, initialOpen = * ); * ``` * - * @return {WPElement} The WPElement to be rendered. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ const PluginPrePublishPanel = compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js b/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js index 5303de703b30b9..e59e6eb96d0574 100644 --- a/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js @@ -82,7 +82,7 @@ function PluginSidebar( props ) { * @param {string} [props.className] An optional class name added to the sidebar body. * @param {string} props.title Title displayed at the top of the sidebar. * @param {boolean} [props.isPinnable=true] Whether to allow to pin sidebar to toolbar. - * @param {string|Element} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. + * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example ES5 * ```js @@ -129,7 +129,7 @@ function PluginSidebar( props ) { * ); * ``` * - * @return {WPElement} Plugin sidebar component. + * @return {import('@wordpress/element').WPComponent} Plugin sidebar component. */ export default compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/hooks/validate-multiple-use/index.js b/packages/edit-post/src/hooks/validate-multiple-use/index.js index ea2958949f7e2d..6dca911db6ed08 100644 --- a/packages/edit-post/src/hooks/validate-multiple-use/index.js +++ b/packages/edit-post/src/hooks/validate-multiple-use/index.js @@ -28,9 +28,9 @@ const enhance = compose( * "original" block is not the current one. Thus, an inexisting * `originalBlockClientId` prop signals that the block is valid. * - * @param {Component} WrappedBlockEdit A filtered BlockEdit instance. + * @param {import('@wordpress/element').WPComponent} WrappedBlockEdit A filtered BlockEdit instance. * - * @return {Component} Enhanced component with merged state data props. + * @return {import('@wordpress/element').WPComponent} Enhanced component with merged state data props. */ withSelect( ( select, block ) => { const multiple = hasBlockSupport( block.name, 'multiple', true ); diff --git a/packages/edit-post/src/store/selectors.js b/packages/edit-post/src/store/selectors.js index 2430ee41087232..fff04ac721fe37 100644 --- a/packages/edit-post/src/store/selectors.js +++ b/packages/edit-post/src/store/selectors.js @@ -78,9 +78,9 @@ export function getPreferences( state ) { * * @param {Object} state Global application state. * @param {string} preferenceKey Preference Key. - * @param {Mixed} defaultValue Default Value. + * @param {*} defaultValue Default Value. * - * @return {Mixed} Preference Value. + * @return {*} Preference Value. */ export function getPreference( state, preferenceKey, defaultValue ) { const preferences = getPreferences( state ); diff --git a/packages/edit-widgets/src/components/widget-area/selection-observer.js b/packages/edit-widgets/src/components/widget-area/selection-observer.js index 3b1cdf5c378e49..6a46ca1d0527f3 100644 --- a/packages/edit-widgets/src/components/widget-area/selection-observer.js +++ b/packages/edit-widgets/src/components/widget-area/selection-observer.js @@ -10,7 +10,7 @@ import { withSelect, withDispatch } from '@wordpress/data'; * can be used to ensuring that only one block appears as selected * when multiple editors exist in a page. * - * @type {WPComponent} + * @type {import('@wordpress/element').WPComponent} */ class SelectionObserver extends Component { diff --git a/packages/editor/src/components/autocompleters/block.js b/packages/editor/src/components/autocompleters/block.js index 70860643ae096b..19a18d8c9032d7 100644 --- a/packages/editor/src/components/autocompleters/block.js +++ b/packages/editor/src/components/autocompleters/block.js @@ -27,7 +27,7 @@ function defaultGetBlockInsertionParentClientId() { * @param {string} rootClientId Client ID of the block for which to retrieve * inserter items. * - * @return {Array} The inserter items for the specified + * @return {Array} The inserter items for the specified * parent. */ function defaultGetInserterItems( rootClientId ) { @@ -68,7 +68,7 @@ const fetchReusableBlocks = once( () => { /** * Creates a blocks repeater for replacing the current block with a selected block type. * - * @return {Completer} A blocks completer. + * @return {import('@wordpress/components').Completer} A blocks completer. */ export function createBlockCompleter( { // Allow store-based selectors to be overridden for unit test. @@ -119,6 +119,6 @@ export function createBlockCompleter( { /** * Creates a blocks repeater for replacing the current block with a selected block type. * - * @return {Completer} A blocks completer. + * @return {import('@wordpress/components').Completer} A blocks completer. */ export default createBlockCompleter(); diff --git a/packages/editor/src/components/autocompleters/user.js b/packages/editor/src/components/autocompleters/user.js index e3965a33f28d6f..9f0b84f39ff59f 100644 --- a/packages/editor/src/components/autocompleters/user.js +++ b/packages/editor/src/components/autocompleters/user.js @@ -6,7 +6,7 @@ import apiFetch from '@wordpress/api-fetch'; /** * A user mentions completer. * - * @type {Completer} + * @type {import('@wordpress/components').Completer} */ export default { name: 'users', diff --git a/packages/editor/src/components/post-type-support-check/index.js b/packages/editor/src/components/post-type-support-check/index.js index 8096e4ccf7f8d9..96d8e8e44b5b02 100644 --- a/packages/editor/src/components/post-type-support-check/index.js +++ b/packages/editor/src/components/post-type-support-check/index.js @@ -12,14 +12,14 @@ import { withSelect } from '@wordpress/data'; * A component which renders its own children only if the current editor post * type supports one of the given `supportKeys` prop. * - * @param {Object} props - * @param {string} [props.postType] Current post type. - * @param {WPElement} props.children Children to be rendered if post - * type supports. - * @param {(string|string[])} props.supportKeys String or string array of keys - * to test. + * @param {Object} props Props. + * @param {string} [props.postType] Current post type. + * @param {import('@wordpress/element').WPElement} props.children Children to be rendered if post + * type supports. + * @param {(string|string[])} props.supportKeys String or string array of keys + * to test. * - * @return {WPElement} Rendered element. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ export function PostTypeSupportCheck( { postType, children, supportKeys } ) { let isSupported = true; diff --git a/packages/editor/src/store/actions.native.js b/packages/editor/src/store/actions.native.js index 17733a0e47b408..0154c92324640e 100644 --- a/packages/editor/src/store/actions.native.js +++ b/packages/editor/src/store/actions.native.js @@ -21,9 +21,7 @@ export function togglePostTitleSelection( isSelected = true ) { /** * Action generator used in signalling that the post should autosave. - * - * @param {Object?} options Extra flags to identify the autosave. */ -export function* autosave( ) { +export function* autosave() { RNReactNativeGutenbergBridge.editorDidAutosave(); } diff --git a/packages/editor/src/store/reducer.js b/packages/editor/src/store/reducer.js index 7014d8a3b1fe56..0bf0ddf3f1bb38 100644 --- a/packages/editor/src/store/reducer.js +++ b/packages/editor/src/store/reducer.js @@ -210,8 +210,8 @@ export function postLock( state = { isLocked: false }, action ) { * * When post saving is locked, the post cannot be published or updated. * - * @param {PostSavingLockState} state Current state. - * @param {Object} action Dispatched action. + * @param {PostLockState} state Current state. + * @param {Object} action Dispatched action. * * @return {PostLockState} Updated state. */ @@ -231,8 +231,8 @@ export function postSavingLock( state = {}, action ) { * * When post autosaving is locked, the post will not autosave. * - * @param {PostAutosavingLockState} state Current state. - * @param {Object} action Dispatched action. + * @param {PostLockState} state Current state. + * @param {Object} action Dispatched action. * * @return {PostLockState} Updated state. */ diff --git a/packages/editor/src/store/selectors.js b/packages/editor/src/store/selectors.js index a8c216d4b2083f..f972ce4c9e3283 100644 --- a/packages/editor/src/store/selectors.js +++ b/packages/editor/src/store/selectors.js @@ -827,7 +827,7 @@ export function getSuggestedPostFormat( state ) { * * @param {Object} state Editor state. * - * @return {WPBlock[]} Filtered set of blocks for save. + * @return {import('@wordpress/blocks').WPBlockType[]} Filtered set of blocks for save. */ export function getBlocksForSerialization( state ) { deprecated( '`core/editor` getBlocksForSerialization selector', { diff --git a/packages/element/README.md b/packages/element/README.md index 0b96812eacb539..89424f857f0cdc 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -148,7 +148,7 @@ _Related_ _Parameters_ -- _component_ `Component`: Component +- _component_ `null`: Component - _target_ `Element`: DOM node into which element should be rendered # **createRef** @@ -167,7 +167,7 @@ Finds the dom node of a React component _Parameters_ -- _component_ `Component`: component's instance +- _component_ `null`: component's instance - _target_ `Element`: DOM node into which element should be rendered # **forwardRef** @@ -183,7 +183,7 @@ _Parameters_ _Returns_ -- `WPComponent`: Enhanced component. +- `Component`: Enhanced component. # **Fragment** @@ -203,7 +203,7 @@ _Returns_ # **isValidElement** -Checks if an object is a valid WPElement +Checks if an object is a valid WPElement. _Parameters_ @@ -240,7 +240,7 @@ _Parameters_ _Returns_ -- `WPElement`: Dangerously-rendering element. +- `null`: Dangerously-rendering component. # **render** @@ -248,8 +248,8 @@ Renders a given element into the target DOM node. _Parameters_ -- _element_ `WPElement`: Element to render -- _target_ `Element`: DOM node into which element should be rendered +- _element_ `null`: Element to render. +- _target_ `Element`: DOM node into which element should be rendered. # **renderToString** @@ -257,7 +257,7 @@ Serializes a React element to string. _Parameters_ -- _element_ `WPElement`: Element to serialize. +- _element_ `null`: Element to serialize. - _context_ `?Object`: Context object. - _legacyContext_ `?Object`: Legacy context object. diff --git a/packages/element/src/raw-html.js b/packages/element/src/raw-html.js index 2fa3618c417d88..ea3f47172de680 100644 --- a/packages/element/src/raw-html.js +++ b/packages/element/src/raw-html.js @@ -13,7 +13,7 @@ import { createElement } from './react'; * @param {string} props.children HTML to render. * @param {Object} props.props Any additonal props to be set on the containing div. * - * @return {WPElement} Dangerously-rendering element. + * @return {import('@wordpress/element').WPComponent} Dangerously-rendering component. */ export default function RawHTML( { children, ...props } ) { // The DIV wrapper will be stripped by serializer, unless there are diff --git a/packages/element/src/react-platform.js b/packages/element/src/react-platform.js index e4ca37da7e11bc..81dbf5fe35acde 100644 --- a/packages/element/src/react-platform.js +++ b/packages/element/src/react-platform.js @@ -13,7 +13,7 @@ import { * * @see https://github.com/facebook/react/issues/10309#issuecomment-318433235 * - * @param {Component} component Component + * @param {import('@wordpress/element').WPComponent} component Component * @param {Element} target DOM node into which element should be rendered */ export { createPortal }; @@ -21,16 +21,16 @@ export { createPortal }; /** * Finds the dom node of a React component * - * @param {Component} component component's instance - * @param {Element} target DOM node into which element should be rendered + * @param {import('@wordpress/element').WPComponent} component component's instance + * @param {Element} target DOM node into which element should be rendered */ export { findDOMNode }; /** * Renders a given element into the target DOM node. * - * @param {WPElement} element Element to render - * @param {Element} target DOM node into which element should be rendered + * @param {import('@wordpress/element').WPElement} element Element to render. + * @param {Element} target DOM node into which element should be rendered. */ export { render }; diff --git a/packages/element/src/react.js b/packages/element/src/react.js index 722085de1fc776..87e3b280106a77 100644 --- a/packages/element/src/react.js +++ b/packages/element/src/react.js @@ -28,6 +28,24 @@ import { } from 'react'; import { isString } from 'lodash'; +/** + * Object containing a React element. + * + * @typedef {import('react').ReactElement} WPElement + */ + +/** + * Object containing a React component. + * + * @typedef {import('react').Component} WPComponent + */ + +/** + * Object containing a React synthetic event. + * + * @typedef {import('react').SyntheticEvent} WPSyntheticEvent + */ + /** * Object that provides utilities for dealing with React children. */ @@ -63,8 +81,8 @@ export { createContext }; * * @param {?(string|Function)} type Tag name or element creator * @param {Object} props Element properties, either attribute - * set to apply to DOM node or values to - * pass through to element creator + * set to apply to DOM node or values to + * pass through to element creator * @param {...WPElement} children Descendant elements * * @return {WPElement} Element. @@ -89,7 +107,7 @@ export { createRef }; * @param {Function} forwarder Function passed `props` and `ref`, expected to * return an element. * - * @return {WPComponent} Enhanced component. + * @return {Component} Enhanced component. */ export { forwardRef }; @@ -99,7 +117,7 @@ export { forwardRef }; export { Fragment }; /** - * Checks if an object is a valid WPElement + * Checks if an object is a valid WPElement. * * @param {Object} objectToCheck The object to be checked. * diff --git a/packages/element/src/serialize.js b/packages/element/src/serialize.js index b700831f1dccd0..2e20032e0e85e1 100644 --- a/packages/element/src/serialize.js +++ b/packages/element/src/serialize.js @@ -348,9 +348,9 @@ function getNormalStylePropertyValue( property, value ) { /** * Serializes a React element to string. * - * @param {WPElement} element Element to serialize. - * @param {?Object} context Context object. - * @param {?Object} legacyContext Legacy context object. + * @param {import('@wordpress/element').WPElement} element Element to serialize. + * @param {?Object} context Context object. + * @param {?Object} legacyContext Legacy context object. * * @return {string} Serialized element. */ diff --git a/packages/jest-puppeteer-axe/src/index.js b/packages/jest-puppeteer-axe/src/index.js index 336cec9bcf8161..d078ca8b21d66d 100644 --- a/packages/jest-puppeteer-axe/src/index.js +++ b/packages/jest-puppeteer-axe/src/index.js @@ -53,13 +53,13 @@ function formatViolations( violations ) { * * @see https://github.com/dequelabs/axe-puppeteer * - * @param {Page} page Puppeteer's page instance. - * @param {?Object} params Optional Axe API options. - * @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 {import('puppeteer').Page} page Puppeteer's page instance. + * @param {?Object} params Optional Axe API options. + * @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. * * @return {Object} A matcher object with two keys `pass` and `message`. */ diff --git a/packages/notices/src/store/actions.js b/packages/notices/src/store/actions.js index f1771b6ca8ae2f..0fed89a60e0f31 100644 --- a/packages/notices/src/store/actions.js +++ b/packages/notices/src/store/actions.js @@ -8,6 +8,17 @@ import { uniqueId } from 'lodash'; */ import { DEFAULT_CONTEXT, DEFAULT_STATUS } from './constants'; +/** + * @typedef {Object} WPNoticeAction Object describing a user action option associated with a notice. + * + * @property {string} label Message to use as action label. + * @property {?string} url Optional URL of resource if action incurs + * browser navigation. + * @property {?Function} onClick Optional function to invoke when action is + * triggered by user. + * + */ + /** * Yields action objects used in signalling that a notice is to be created. * diff --git a/packages/notices/src/store/selectors.js b/packages/notices/src/store/selectors.js index 3a0bc75ad0f02a..2d67195dcc7fc2 100644 --- a/packages/notices/src/store/selectors.js +++ b/packages/notices/src/store/selectors.js @@ -34,18 +34,7 @@ const DEFAULT_NOTICES = []; * @property {boolean} speak Whether the notice content should be * announced to screen readers. Defaults to * `true`. - * @property {WPNoticeAction[]} actions User actions to present with notice. - * - */ - -/** - * @typedef {Object} WPNoticeAction Object describing a user action option associated with a notice. - * - * @property {string} label Message to use as action label. - * @property {?string} url Optional URL of resource if action incurs - * browser navigation. - * @property {?Function} onClick Optional function to invoke when action is - * triggered by user. + * @property {import('./actions').WPNoticeAction[]} actions User actions to present with notice. * */ diff --git a/packages/nux/src/store/selectors.js b/packages/nux/src/store/selectors.js index 9225bd97077eee..58decf89455191 100644 --- a/packages/nux/src/store/selectors.js +++ b/packages/nux/src/store/selectors.js @@ -7,7 +7,7 @@ import { includes, difference, keys, has } from 'lodash'; /** * An object containing information about a guide. * - * @typedef {Object} NUX.GuideInfo + * @typedef {Object} NUXGuideInfo * @property {string[]} tipIds Which tips the guide contains. * @property {?string} currentTipId The guide's currently showing tip. * @property {?string} nextTipId The guide's next tip to show. @@ -20,7 +20,7 @@ import { includes, difference, keys, has } from 'lodash'; * @param {Object} state Global application state. * @param {string} tipId The tip to query. * - * @return {?NUX.GuideInfo} Information about the associated guide. + * @return {?NUXGuideInfo} Information about the associated guide. */ export const getAssociatedGuide = createSelector( ( state, tipId ) => { diff --git a/packages/plugins/README.md b/packages/plugins/README.md index 2875c76b0fa8da..1ad70184678136 100644 --- a/packages/plugins/README.md +++ b/packages/plugins/README.md @@ -26,7 +26,7 @@ _Parameters_ _Returns_ -- `?Object`: Plugin setting. +- `?WPPlugin`: Plugin setting. # **getPlugins** @@ -34,7 +34,7 @@ Returns all registered plugins. _Returns_ -- `Array`: Plugin settings. +- `Array`: Plugin settings. # **PluginArea** @@ -71,7 +71,7 @@ const Layout = () => ( _Returns_ -- `WPElement`: Plugin area. +- `null`: The component to be rendered. # **registerPlugin** @@ -143,14 +143,12 @@ registerPlugin( 'plugin-name', { _Parameters_ -- _name_ `string`: A string identifying the plugin. Must be unique across all registered plugins. -- _settings_ `Object`: The settings for this plugin. -- _settings.icon_ `(string|WPElement|Function)`: An icon to be shown in the UI. It can be a slug of the Dashicon, or an element (or function returning an element) if you choose to render your own SVG. -- _settings.render_ `Function`: A component containing the UI elements to be rendered. +- _name_ `string`: A string identifying the plugin.Must be unique across all registered plugins. +- _settings_ `WPPlugin`: The settings for this plugin. _Returns_ -- `Object`: The final plugin settings object. +- `WPPlugin`: The final plugin settings object. # **unregisterPlugin** @@ -191,7 +189,7 @@ _Parameters_ _Returns_ -- `Component`: Enhanced component with injected context as props. +- `null`: Enhanced component with injected context as props. diff --git a/packages/plugins/src/api/index.js b/packages/plugins/src/api/index.js index 6e6ea102a80ffd..81ec513a0351f0 100644 --- a/packages/plugins/src/api/index.js +++ b/packages/plugins/src/api/index.js @@ -10,6 +10,22 @@ import { applyFilters, doAction } from '@wordpress/hooks'; */ import { isFunction } from 'lodash'; +/** + * Defined behavior of a plugin type. + * + * @typedef {Object} WPPlugin + * + * @property {string} name A string identifying the plugin. Must be + * unique across all registered plugins. + * unique across all registered plugins. + * @property {string|import('@wordpress/element').WPElement|Function} icon An icon to be shown in the UI. It can + * be a slug of the Dashicon, or an element + * (or function returning an element) if you + * choose to render your own SVG. + * @property {Function} render A component containing the UI elements + * to be rendered. + */ + /** * Plugin definitions keyed by plugin name. * @@ -20,11 +36,9 @@ const plugins = {}; /** * Registers a plugin to the editor. * - * @param {string} name A string identifying the plugin. Must be unique across all registered plugins. - * @param {Object} settings The settings for this plugin. - * @param {string|WPElement|Function} settings.icon An icon to be shown in the UI. It can be a slug of the Dashicon, - * or an element (or function returning an element) if you choose to render your own SVG. - * @param {Function} settings.render A component containing the UI elements to be rendered. + * @param {string} name A string identifying the plugin.Must be + * unique across all registered plugins. + * @param {WPPlugin} settings The settings for this plugin. * * @example ES5 * ```js @@ -90,7 +104,7 @@ const plugins = {}; * } ); * ``` * - * @return {Object} The final plugin settings object. + * @return {WPPlugin} The final plugin settings object. */ export function registerPlugin( name, settings ) { if ( typeof settings !== 'object' ) { @@ -181,7 +195,7 @@ export function unregisterPlugin( name ) { * * @param {string} name Plugin name. * - * @return {?Object} Plugin setting. + * @return {?WPPlugin} Plugin setting. */ export function getPlugin( name ) { return plugins[ name ]; @@ -190,7 +204,7 @@ export function getPlugin( name ) { /** * Returns all registered plugins. * - * @return {Array} Plugin settings. + * @return {WPPlugin[]} Plugin settings. */ export function getPlugins() { return Object.values( plugins ); diff --git a/packages/plugins/src/components/plugin-area/index.js b/packages/plugins/src/components/plugin-area/index.js index 1cf6f15b528795..01eda548d695c2 100644 --- a/packages/plugins/src/components/plugin-area/index.js +++ b/packages/plugins/src/components/plugin-area/index.js @@ -47,7 +47,7 @@ import { getPlugins } from '../../api'; * ); * ``` * - * @return {WPElement} Plugin area. + * @return {import('@wordpress/element').WPComponent} The component to be rendered. */ class PluginArea extends Component { constructor() { diff --git a/packages/plugins/src/components/plugin-context/index.js b/packages/plugins/src/components/plugin-context/index.js index 75fb1b8f1dea01..0ac95bd43bb62a 100644 --- a/packages/plugins/src/components/plugin-context/index.js +++ b/packages/plugins/src/components/plugin-context/index.js @@ -19,7 +19,7 @@ export { Provider as PluginContextProvider }; * expected to return object of props to * merge with the component's own props. * - * @return {Component} Enhanced component with injected context as props. + * @return {import('@wordpress/element').WPComponent} Enhanced component with injected context as props. */ export const withPluginContext = ( mapContextToProps ) => createHigherOrderComponent( ( OriginalComponent ) => { return ( props ) => ( diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md index 46a78502ff3ed4..fec5018aac0ac5 100644 --- a/packages/rich-text/README.md +++ b/packages/rich-text/README.md @@ -216,11 +216,7 @@ behavior. _Parameters_ - _name_ `string`: Format name. -- _settings_ `Object`: Format settings. -- _settings.tagName_ `string`: The HTML tag this format will wrap the selection with. -- _settings.className_ `[string]`: A class to match the format. -- _settings.title_ `string`: Name of the format. -- _settings.edit_ `Function`: Should return a component for the user to interact with the new registered format. +- _settings_ `WPFormat`: Format settings. _Returns_ @@ -347,7 +343,7 @@ _Parameters_ _Returns_ -- `(WPFormat|undefined)`: The previous format value, if it has been successfully unregistered; otherwise `undefined`. +- `null`: The previous format value, if it has been successfully unregistered; otherwise `undefined`. diff --git a/packages/rich-text/src/component/index.js b/packages/rich-text/src/component/index.js index c82feae869d1e7..871f3450e30b1c 100644 --- a/packages/rich-text/src/component/index.js +++ b/packages/rich-text/src/component/index.js @@ -204,7 +204,7 @@ class RichText extends Component { * * Saves the pasted data as plain text in `pastedPlainText`. * - * @param {PasteEvent} event The paste event. + * @param {ClipboardEvent} event The paste event. */ onPaste( event ) { const { formatTypes, onPaste } = this.props; @@ -337,7 +337,7 @@ class RichText extends Component { /** * Handle input on the next selection change event. * - * @param {SyntheticEvent} event Synthetic input event. + * @param {import('@wordpress/element').WPSyntheticEvent} event Synthetic input event. */ onInput( event ) { // For Input Method Editor (IME), used in Chinese, Japanese, and Korean @@ -437,7 +437,7 @@ class RichText extends Component { * native events, `keyup`, `mouseup` and `touchend` synthetic events, and * animation frames after the `focus` event. * - * @param {Event|SyntheticEvent|DOMHighResTimeStamp} event + * @param {Event|import('@wordpress/element').WPSyntheticEvent|DOMHighResTimeStamp} event */ onSelectionChange( event ) { if ( @@ -579,7 +579,7 @@ class RichText extends Component { * - delete content if everything is selected, * - trigger the onDelete prop when selection is uncollapsed and at an edge. * - * @param {SyntheticEvent} event A synthetic keyboard event. + * @param {import('@wordpress/element').WPSyntheticEvent} event A synthetic keyboard event. */ handleDelete( event ) { const { keyCode } = event; @@ -637,7 +637,7 @@ class RichText extends Component { /** * Triggers the `onEnter` prop on keydown. * - * @param {SyntheticEvent} event A synthetic keyboard event. + * @param {import('@wordpress/element').WPSyntheticEvent} event A synthetic keyboard event. */ handleEnter( event ) { if ( event.keyCode !== ENTER ) { @@ -662,7 +662,7 @@ class RichText extends Component { /** * Indents list items on space keydown. * - * @param {SyntheticEvent} event A synthetic keyboard event. + * @param {import('@wordpress/element').WPSyntheticEvent} event A synthetic keyboard event. */ handleSpace( event ) { const { keyCode, shiftKey, altKey, metaKey, ctrlKey } = event; @@ -699,7 +699,7 @@ class RichText extends Component { * navigation is handled separately to move correctly around format * boundaries. * - * @param {SyntheticEvent} event A synthetic keyboard event. + * @param {import('@wordpress/element').WPSyntheticEvent} event A synthetic keyboard event. */ handleHorizontalNavigation( event ) { const { keyCode, shiftKey, altKey, metaKey, ctrlKey } = event; @@ -805,7 +805,7 @@ class RichText extends Component { * Select object when they are clicked. The browser will not set any * selection when clicking e.g. an image. * - * @param {SyntheticEvent} event Synthetic mousedown or touchstart event. + * @param {import('@wordpress/element').WPSyntheticEvent} event Synthetic mousedown or touchstart event. */ onPointerDown( event ) { const { target } = event; diff --git a/packages/rich-text/src/register-format-type.js b/packages/rich-text/src/register-format-type.js index e6efc99f5fec97..84a158167b860f 100644 --- a/packages/rich-text/src/register-format-type.js +++ b/packages/rich-text/src/register-format-type.js @@ -10,16 +10,25 @@ import { select, dispatch, withSelect, withDispatch } from '@wordpress/data'; import { addFilter } from '@wordpress/hooks'; import { compose } from '@wordpress/compose'; +/** + * @typedef {Object} WPFormat + * + * @property {string} name A string identifying the format. Must be + * unique across all registered formats. + * @property {string} tagName The HTML tag this format will wrap the + * selection with. + * @property {string} [className] A class to match the format. + * @property {string} title Name of the format. + * @property {Function} edit Should return a component for the user to + * interact with the new registered format. + */ + /** * Registers a new format provided a unique name and an object defining its * behavior. * * @param {string} name Format name. - * @param {Object} settings Format settings. - * @param {string} settings.tagName The HTML tag this format will wrap the selection with. - * @param {string} [settings.className] A class to match the format. - * @param {string} settings.title Name of the format. - * @param {Function} settings.edit Should return a component for the user to interact with the new registered format. + * @param {WPFormat} settings Format settings. * * @return {WPFormat|undefined} The format, if it has been successfully registered; * otherwise `undefined`. diff --git a/packages/rich-text/src/to-dom.js b/packages/rich-text/src/to-dom.js index 9d7aed3cfdfd00..730a38587114c4 100644 --- a/packages/rich-text/src/to-dom.js +++ b/packages/rich-text/src/to-dom.js @@ -67,7 +67,7 @@ function getNodeByPath( node, path ) { * each call to `createEmpty`. Therefore, you should not hold a reference to * the value to operate upon asynchronously, as it may have unexpected results. * - * @return {WPRichTextTree} RichText tree. + * @return {Object} RichText tree. */ const createEmpty = () => createElement( document, '' ); diff --git a/packages/rich-text/src/unregister-format-type.js b/packages/rich-text/src/unregister-format-type.js index a70c1d1d417f2b..2c4b36f8883e02 100644 --- a/packages/rich-text/src/unregister-format-type.js +++ b/packages/rich-text/src/unregister-format-type.js @@ -9,8 +9,8 @@ import { removeFilter } from '@wordpress/hooks'; * * @param {string} name Format name. * - * @return {WPFormat|undefined} The previous format value, if it has been successfully - * unregistered; otherwise `undefined`. + * @return {import('./register-format-type').WPFormat|undefined} The previous format value, + * if it has been successfully unregistered; otherwise `undefined`. */ export function unregisterFormatType( name ) { const oldFormat = select( 'core/rich-text' ).getFormatType( name ); From 0aeb619fb3dba0d25327c7856716f2930d16a18c Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Wed, 23 Oct 2019 18:25:29 +0200 Subject: [PATCH 2/2] Add WordPress type definitions to the list of names recognized by JSDoc linter --- .../developers/data/data-core-block-editor.md | 4 +- .../developers/data/data-core-editor.md | 2 +- packages/block-editor/README.md | 2 +- .../src/components/block-edit/context.js | 6 +-- .../src/components/block-list/breadcrumb.js | 2 +- .../src/components/block-preview/index.js | 2 +- .../src/components/colors/with-colors.js | 2 +- .../components/ignore-nested-events/index.js | 2 +- .../src/components/inserter/index.js | 4 +- .../src/components/inserter/index.native.js | 4 +- .../src/components/media-upload/index.js | 2 +- .../src/components/provider/index.js | 4 +- .../src/components/provider/index.native.js | 8 +-- .../rich-text/remove-browser-shortcuts.js | 4 +- .../src/components/typewriter/index.js | 2 +- packages/block-editor/src/hooks/anchor.js | 4 +- .../src/hooks/custom-class-name.js | 4 +- packages/block-editor/src/store/selectors.js | 6 +-- packages/block-library/src/columns/utils.js | 38 +++++++------- packages/blocks/README.md | 12 ++--- packages/blocks/src/api/children.js | 6 +-- packages/blocks/src/api/parser.js | 8 +-- packages/blocks/src/api/registration.js | 44 ++++++++-------- packages/blocks/src/api/serializer.js | 12 ++--- packages/blocks/src/api/utils.js | 10 ++-- .../src/block-content-provider/index.js | 4 +- packages/components/src/autocomplete/index.js | 8 +-- packages/components/src/date-time/date.js | 2 +- .../higher-order/with-focus-return/index.js | 10 ++-- .../src/higher-order/with-notices/index.js | 4 +- .../with-spoken-messages/index.js | 4 +- packages/components/src/menu-item/index.js | 2 +- packages/components/src/modal/frame.js | 2 +- packages/components/src/modal/index.js | 2 +- packages/components/src/scroll-lock/index.js | 2 +- packages/components/src/toolbar/index.js | 12 ++--- packages/compose/README.md | 14 ++--- .../compose/src/higher-order/pure/index.js | 2 +- .../higher-order/with-instance-id/index.js | 4 +- .../higher-order/with-safe-timeout/index.js | 4 +- .../src/higher-order/with-state/index.js | 2 +- .../create-higher-order-component/index.js | 2 +- packages/data/README.md | 8 +-- .../src/components/with-dispatch/index.js | 2 +- .../src/components/with-registry/index.js | 4 +- .../data/src/components/with-select/index.js | 2 +- packages/data/src/factory.js | 6 +-- packages/data/src/namespace-store/index.js | 22 ++++---- .../data/src/plugins/persistence/index.js | 6 +-- .../data/src/resolvers-cache-middleware.js | 8 +-- packages/date/README.md | 8 +-- packages/date/src/index.js | 50 +++++++++--------- packages/e2e-test-utils/README.md | 4 +- .../src/enable-page-dialog-accept.js | 2 +- ...-sidebar-panel-toggle-button-with-title.js | 2 +- .../src/find-sidebar-panel-with-title.js | 2 +- .../editor/various/adding-blocks.test.js | 2 +- .../specs/editor/various/preview.test.js | 2 +- packages/edit-post/README.md | 30 +++++------ .../plugin-block-settings-menu-item.js | 4 +- .../header/plugin-more-menu-item/index.js | 4 +- .../plugin-sidebar-more-menu-item/index.js | 4 +- .../plugin-document-setting-panel/index.js | 4 +- .../plugin-post-publish-panel/index.js | 4 +- .../sidebar/plugin-post-status-info/index.js | 2 +- .../sidebar/plugin-pre-publish-panel/index.js | 18 +++---- .../sidebar/plugin-sidebar/index.js | 4 +- .../src/hooks/validate-multiple-use/index.js | 4 +- .../widget-area/selection-observer.js | 2 +- .../src/components/autocompleters/block.js | 6 +-- .../src/components/autocompleters/user.js | 2 +- .../post-type-support-check/index.js | 8 +-- packages/editor/src/store/selectors.js | 2 +- packages/element/README.md | 19 ++++--- packages/element/src/raw-html.js | 2 +- packages/element/src/react-platform.js | 14 ++--- packages/element/src/react.js | 8 +-- packages/element/src/serialize.js | 6 +-- packages/eslint-plugin/configs/jsdoc.js | 52 +++++++++++++++++++ packages/jest-puppeteer-axe/src/index.js | 14 ++--- packages/notices/src/store/selectors.js | 2 +- packages/plugins/README.md | 4 +- packages/plugins/src/api/index.js | 18 +++---- .../src/components/plugin-area/index.js | 2 +- .../src/components/plugin-context/index.js | 2 +- packages/rich-text/README.md | 2 +- packages/rich-text/src/component/index.js | 14 ++--- .../rich-text/src/unregister-format-type.js | 4 +- 88 files changed, 356 insertions(+), 309 deletions(-) diff --git a/docs/designers-developers/developers/data/data-core-block-editor.md b/docs/designers-developers/developers/data/data-core-block-editor.md index 5d994934d64d7b..6f654f23e16090 100644 --- a/docs/designers-developers/developers/data/data-core-block-editor.md +++ b/docs/designers-developers/developers/data/data-core-block-editor.md @@ -233,7 +233,7 @@ _Parameters_ _Returns_ -- `null`: Block objects. +- `Array`: Block objects. # **getBlockSelectionEnd** @@ -345,7 +345,7 @@ _Parameters_ _Returns_ -- `Array`: Items that appear in inserter. +- `Array`: Items that appear in inserter. # **getLastMultiSelectedBlockClientId** diff --git a/docs/designers-developers/developers/data/data-core-editor.md b/docs/designers-developers/developers/data/data-core-editor.md index 29c1fc810e993f..8b20edac6d37c1 100644 --- a/docs/designers-developers/developers/data/data-core-editor.md +++ b/docs/designers-developers/developers/data/data-core-editor.md @@ -203,7 +203,7 @@ _Parameters_ _Returns_ -- `null`: Filtered set of blocks for save. +- `Array`: Filtered set of blocks for save. # **getClientIdsOfDescendants** diff --git a/packages/block-editor/README.md b/packages/block-editor/README.md index e061490c7a6027..8df8a36e350eb7 100644 --- a/packages/block-editor/README.md +++ b/packages/block-editor/README.md @@ -137,7 +137,7 @@ _Parameters_ _Returns_ -- `null`: The component to be rendered. +- `WPComponent`: The component to be rendered. # **BlockSelectionClearer** diff --git a/packages/block-editor/src/components/block-edit/context.js b/packages/block-editor/src/components/block-edit/context.js index 74f7f4c6ad4532..2f949882593d90 100644 --- a/packages/block-editor/src/components/block-edit/context.js +++ b/packages/block-editor/src/components/block-edit/context.js @@ -27,7 +27,7 @@ export { Provider as BlockEditContextProvider }; * expected to return object of props to * merge with the component's own props. * - * @return {import('@wordpress/element').WPComponent} Enhanced component with injected context as props. + * @return {WPComponent} Enhanced component with injected context as props. */ export const withBlockEditContext = ( mapContextToProps ) => createHigherOrderComponent( ( OriginalComponent ) => { return ( props ) => ( @@ -46,9 +46,9 @@ export const withBlockEditContext = ( mapContextToProps ) => createHigherOrderCo * A Higher Order Component used to render conditionally the wrapped * component only when the BlockEdit has selected state set. * - * @param {import('@wordpress/element').WPComponent} OriginalComponent Component to wrap. + * @param {WPComponent} OriginalComponent Component to wrap. * - * @return {import('@wordpress/element').WPComponent} Component which renders only when the BlockEdit is selected. + * @return {WPComponent} Component which renders only when the BlockEdit is selected. */ export const ifBlockEditSelected = createHigherOrderComponent( ( OriginalComponent ) => { return ( props ) => ( diff --git a/packages/block-editor/src/components/block-list/breadcrumb.js b/packages/block-editor/src/components/block-list/breadcrumb.js index 56bc7e840d47ec..b167149778843f 100644 --- a/packages/block-editor/src/components/block-list/breadcrumb.js +++ b/packages/block-editor/src/components/block-list/breadcrumb.js @@ -16,7 +16,7 @@ import BlockTitle from '../block-title'; * the root block. * * @param {string} props.clientId Client ID of block. - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ const BlockBreadcrumb = forwardRef( ( { clientId }, ref ) => { const { setNavigationMode } = useDispatch( 'core/block-editor' ); diff --git a/packages/block-editor/src/components/block-preview/index.js b/packages/block-editor/src/components/block-preview/index.js index 9e8fb4982d72b9..00ae9233a12501 100644 --- a/packages/block-editor/src/components/block-preview/index.js +++ b/packages/block-editor/src/components/block-preview/index.js @@ -137,7 +137,7 @@ export function BlockPreview( { blocks, viewportWidth = 700, padding, settings } * * @param {Array|Object} blocks A block instance (object) or an array of blocks to be previewed. * @param {number} viewportWidth Width of the preview container in pixels. Controls at what size the blocks will be rendered inside the preview. Default: 700. - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ export default withSelect( ( select ) => { return { diff --git a/packages/block-editor/src/components/colors/with-colors.js b/packages/block-editor/src/components/colors/with-colors.js index 69d04f2f625189..4544c6c8c49e1e 100644 --- a/packages/block-editor/src/components/colors/with-colors.js +++ b/packages/block-editor/src/components/colors/with-colors.js @@ -49,7 +49,7 @@ const withEditorColorPalette = () => withSelect( ( select ) => { * @param {Array} colorTypes An array of color types (e.g. 'backgroundColor, borderColor). * @param {Function} withColorPalette A HOC for injecting the 'colors' prop into the WrappedComponent. * - * @return {import('@wordpress/element').WPComponent} The component that can be used as a HOC. + * @return {WPComponent} The component that can be used as a HOC. */ function createColorHOC( colorTypes, withColorPalette ) { const colorMap = reduce( colorTypes, ( colorObject, colorType ) => { diff --git a/packages/block-editor/src/components/ignore-nested-events/index.js b/packages/block-editor/src/components/ignore-nested-events/index.js index df1a49da069904..92bbe5ed44c639 100644 --- a/packages/block-editor/src/components/ignore-nested-events/index.js +++ b/packages/block-editor/src/components/ignore-nested-events/index.js @@ -20,7 +20,7 @@ import { Component, forwardRef, createElement } from '@wordpress/element'; * element should stop propagation but not invoke a callback handler, since it * would be assumed these are invoked by the child element. * - * @type {import('@wordpress/element').WPComponent} + * @type {WPComponent} */ export class IgnoreNestedEvents extends Component { constructor() { diff --git a/packages/block-editor/src/components/inserter/index.js b/packages/block-editor/src/components/inserter/index.js index 12eae37767fb21..5abb1ae4ef9230 100644 --- a/packages/block-editor/src/components/inserter/index.js +++ b/packages/block-editor/src/components/inserter/index.js @@ -51,7 +51,7 @@ class Inserter extends Component { * pressed. * @param {boolean} options.isOpen Whether dropdown is currently open. * - * @return {import('@wordpress/element').WPElement} Dropdown toggle element. + * @return {WPElement} Dropdown toggle element. */ renderToggle( { onToggle, isOpen } ) { const { @@ -69,7 +69,7 @@ class Inserter extends Component { * @param {Function} options.onClose Callback to invoke when dropdown is * closed. * - * @return {import('@wordpress/element').WPElement} Dropdown content element. + * @return {WPElement} Dropdown content element. */ renderContent( { onClose } ) { const { rootClientId, clientId, isAppender, showInserterHelpPanel } = this.props; diff --git a/packages/block-editor/src/components/inserter/index.native.js b/packages/block-editor/src/components/inserter/index.native.js index 0170d16577f912..4c06402af38214 100644 --- a/packages/block-editor/src/components/inserter/index.native.js +++ b/packages/block-editor/src/components/inserter/index.native.js @@ -50,7 +50,7 @@ class Inserter extends Component { * pressed. * @param {boolean} options.isOpen Whether dropdown is currently open. * - * @return {import('@wordpress/element').WPElement} Dropdown toggle element. + * @return {WPElement} Dropdown toggle element. */ renderToggle( { onToggle, isOpen } ) { const { @@ -69,7 +69,7 @@ class Inserter extends Component { * @param {Function} options.onClose Callback to invoke when dropdown is * closed. * - * @return {import('@wordpress/element').WPElement} Dropdown content element. + * @return {WPElement} Dropdown content element. */ renderContent( { onClose, isOpen } ) { const { rootClientId, clientId, isAppender } = this.props; diff --git a/packages/block-editor/src/components/media-upload/index.js b/packages/block-editor/src/components/media-upload/index.js index 222aec5a301185..2318ef93d5e4f4 100644 --- a/packages/block-editor/src/components/media-upload/index.js +++ b/packages/block-editor/src/components/media-upload/index.js @@ -8,7 +8,7 @@ import { withFilters } from '@wordpress/components'; * an integration with the core blocks that handle media files. By default it renders nothing but * it provides a way to have it overridden with the `editor.MediaUpload` filter. * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ const MediaUpload = () => null; diff --git a/packages/block-editor/src/components/provider/index.js b/packages/block-editor/src/components/provider/index.js index 519e36d6410581..c2b29f13fa74ac 100644 --- a/packages/block-editor/src/components/provider/index.js +++ b/packages/block-editor/src/components/provider/index.js @@ -73,8 +73,8 @@ class BlockEditorProvider extends Component { * This needs to be done synchronously after state changes (instead of using * `componentDidUpdate`) in order to avoid batching these changes. * - * @param {import('@wordpress/data').WPDataRegistry} registry Registry from which block editor - * dispatch is to be overridden. + * @param {WPDataRegistry} registry Registry from which block editor + * dispatch is to be overridden. */ attachChangeObserver( registry ) { if ( this.unsubscribe ) { diff --git a/packages/block-editor/src/components/provider/index.native.js b/packages/block-editor/src/components/provider/index.native.js index eccb227e519650..fca4fab5ddbdee 100644 --- a/packages/block-editor/src/components/provider/index.native.js +++ b/packages/block-editor/src/components/provider/index.native.js @@ -10,9 +10,9 @@ import { createHigherOrderComponent, compose } from '@wordpress/compose'; * Higher-order component which renders the original component with the current * registry context passed as its `registry` prop. * - * @param {import('@wordpress/element').WPComponent} OriginalComponent Original component. + * @param {WPComponent} OriginalComponent Original component. * - * @return {import('@wordpress/element').WPComponent} Enhanced component. + * @return {WPComponent} Enhanced component. */ const withRegistry = createHigherOrderComponent( ( OriginalComponent ) => ( props ) => ( @@ -75,8 +75,8 @@ class BlockEditorProvider extends Component { * This needs to be done synchronously after state changes (instead of using * `componentDidUpdate`) in order to avoid batching these changes. * - * @param {import('@wordpress/data').WPDataRegistry} registry Registry from which block editor - * dispatch is to be overridden. + * @param {WPDataRegistry} registry Registry from which block editor + * dispatch is to be overridden. */ attachChangeObserver( registry ) { if ( this.unsubscribe ) { diff --git a/packages/block-editor/src/components/rich-text/remove-browser-shortcuts.js b/packages/block-editor/src/components/rich-text/remove-browser-shortcuts.js index ee275d3edcccb5..9eee7b641a0e61 100644 --- a/packages/block-editor/src/components/rich-text/remove-browser-shortcuts.js +++ b/packages/block-editor/src/components/rich-text/remove-browser-shortcuts.js @@ -25,7 +25,7 @@ const HANDLED_SHORTCUTS = [ * shortcuts. Since shortcuts never change, the element can be considered * static, and can be skipped in reconciliation. * - * @type {import('@wordpress/element').WPElement} + * @type {WPElement} */ const SHORTCUTS_ELEMENT = ( SHORTCUTS_ELEMENT; diff --git a/packages/block-editor/src/components/typewriter/index.js b/packages/block-editor/src/components/typewriter/index.js index d636d13e025baf..d2869ab03b2c01 100644 --- a/packages/block-editor/src/components/typewriter/index.js +++ b/packages/block-editor/src/components/typewriter/index.js @@ -100,7 +100,7 @@ class Typewriter extends Component { * Maintains the scroll position after a selection change caused by a * keyboard event. * - * @param {import('@wordpress/element').WPSyntheticEvent} event Synthetic keyboard event. + * @param {WPSyntheticEvent} event Synthetic keyboard event. */ maintainCaretPosition( { keyCode } ) { if ( ! this.isSelectionEligibleForScroll() ) { diff --git a/packages/block-editor/src/hooks/anchor.js b/packages/block-editor/src/hooks/anchor.js index 15a9d060769bd4..5f8f1ca25879f5 100644 --- a/packages/block-editor/src/hooks/anchor.js +++ b/packages/block-editor/src/hooks/anchor.js @@ -56,9 +56,9 @@ export function addAttribute( settings ) { * Override the default edit UI to include a new block inspector control for * assigning the anchor ID, if block supports anchor. * - * @param {import('@wordpress/element').WPComponent} BlockEdit Original component. + * @param {WPComponent} BlockEdit Original component. * - * @return {import('@wordpress/element').WPComponent} Wrapped component. + * @return {WPComponent} Wrapped component. */ export const withInspectorControl = createHigherOrderComponent( ( BlockEdit ) => { return ( props ) => { diff --git a/packages/block-editor/src/hooks/custom-class-name.js b/packages/block-editor/src/hooks/custom-class-name.js index 17792d692f8947..dfbceb627389cc 100644 --- a/packages/block-editor/src/hooks/custom-class-name.js +++ b/packages/block-editor/src/hooks/custom-class-name.js @@ -47,9 +47,9 @@ export function addAttribute( settings ) { * Override the default edit UI to include a new block inspector control for * assigning the custom class name, if block supports custom class name. * - * @param {import('@wordpress/element').WPComponent} BlockEdit Original component. + * @param {WPComponent} BlockEdit Original component. * - * @return {import('@wordpress/element').WPComponent} Wrapped component. + * @return {WPComponent} Wrapped component. */ export const withInspectorControl = createHigherOrderComponent( ( BlockEdit ) => { return ( props ) => { diff --git a/packages/block-editor/src/store/selectors.js b/packages/block-editor/src/store/selectors.js index 09cbcf261ebb39..ad3cde1d7cb775 100644 --- a/packages/block-editor/src/store/selectors.js +++ b/packages/block-editor/src/store/selectors.js @@ -265,7 +265,7 @@ export const getGlobalBlockCount = createSelector( * @param {Object} state Editor state. * @param {string[]} clientIds Client IDs for which blocks are to be returned. * - * @return {import('@wordpress/blocks').WPBlockType[]} Block objects. + * @return {WPBlock[]} Block objects. */ export const getBlocksByClientId = createSelector( ( state, clientIds ) => map( @@ -1125,9 +1125,9 @@ const canIncludeBlockTypeInInserter = ( state, blockType, rootClientId ) => { * @param {Object} state Editor state. * @param {?string} rootClientId Optional root client ID of block list. * - * @return {EditorInserterItem[]} Items that appear in inserter. + * @return {WPEditorInserterItem[]} Items that appear in inserter. * - * @typedef {Object} EditorInserterItem + * @typedef {Object} WPEditorInserterItem * @property {string} id Unique identifier for the item. * @property {string} name The type of block to create. * @property {Object} initialAttributes Attributes to pass to the newly created block. diff --git a/packages/block-library/src/columns/utils.js b/packages/block-library/src/columns/utils.js index 33c77d2dace166..a6773d469c98f7 100644 --- a/packages/block-library/src/columns/utils.js +++ b/packages/block-library/src/columns/utils.js @@ -38,10 +38,10 @@ export const toWidthPrecision = ( value ) => * when the given block is the last block in the set. For the last block, the * behavior is reversed. * - * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. - * @param {string} clientId Client ID to consider for adjacent blocks. + * @param {WPBlock[]} blocks Block objects. + * @param {string} clientId Client ID to consider for adjacent blocks. * - * @return {import('@wordpress/blocks').WPBlockType[]} Adjacent block objects. + * @return {WPBlock[]} Adjacent block objects. */ export function getAdjacentBlocks( blocks, clientId ) { const index = findIndex( blocks, { clientId } ); @@ -54,8 +54,8 @@ export function getAdjacentBlocks( blocks, clientId ) { * Returns an effective width for a given block. An effective width is equal to * its attribute value if set, or a computed value assuming equal distribution. * - * @param {import('@wordpress/blocks').WPBlockType} block Block object. - * @param {number} totalBlockCount Total number of blocks in Columns. + * @param {WPBlock} block Block object. + * @param {number} totalBlockCount Total number of blocks in Columns. * * @return {number} Effective column width. */ @@ -67,9 +67,9 @@ export function getEffectiveColumnWidth( block, totalBlockCount ) { /** * Returns the total width occupied by the given set of column blocks. * - * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. - * @param {?number} totalBlockCount Total number of blocks in Columns. - * Defaults to number of blocks passed. + * @param {WPBlock[]} blocks Block objects. + * @param {?number} totalBlockCount Total number of blocks in Columns. + * Defaults to number of blocks passed. * * @return {number} Total width occupied by blocks. */ @@ -80,9 +80,9 @@ export function getTotalColumnsWidth( blocks, totalBlockCount = blocks.length ) /** * Returns an object of `clientId` → `width` of effective column widths. * - * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. - * @param {?number} totalBlockCount Total number of blocks in Columns. - * Defaults to number of blocks passed. + * @param {WPBlock[]} blocks Block objects. + * @param {?number} totalBlockCount Total number of blocks in Columns. + * Defaults to number of blocks passed. * * @return {Object} Column widths. */ @@ -98,10 +98,10 @@ export function getColumnWidths( blocks, totalBlockCount = blocks.length ) { * proportional to their current widths, constrained or expanded to fit within * the given available width. * - * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. - * @param {number} availableWidth Maximum width to fit within. - * @param {?number} totalBlockCount Total number of blocks in Columns. - * Defaults to number of blocks passed. + * @param {WPBlock[]} blocks Block objects. + * @param {number} availableWidth Maximum width to fit within. + * @param {?number} totalBlockCount Total number of blocks in Columns. + * Defaults to number of blocks passed. * * @return {Object} Redistributed column widths. */ @@ -120,7 +120,7 @@ export function getRedistributedColumnWidths( blocks, availableWidth, totalBlock * Returns true if column blocks within the provided set are assigned with * explicit widths, or false otherwise. * - * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. + * @param {WPBlock[]} blocks Block objects. * * @return {boolean} Whether columns have explicit widths. */ @@ -132,10 +132,10 @@ export function hasExplicitColumnWidths( blocks ) { * Returns a copy of the given set of blocks with new widths assigned from the * provided object of redistributed column widths. * - * @param {import('@wordpress/blocks').WPBlockType[]} blocks Block objects. - * @param {Object} widths Redistributed column widths. + * @param {WPBlock[]} blocks Block objects. + * @param {Object} widths Redistributed column widths. * - * @return {import('@wordpress/blocks').WPBlockType[]} blocks Mapped block objects. + * @return {WPBlock[]} blocks Mapped block objects. */ export function getMappedColumnWidths( blocks, widths ) { return blocks.map( ( block ) => merge( {}, block, { diff --git a/packages/blocks/README.md b/packages/blocks/README.md index 95832b946e97e6..97a4e95676fc28 100644 --- a/packages/blocks/README.md +++ b/packages/blocks/README.md @@ -517,7 +517,7 @@ which means the block is unmodified. _Parameters_ -- _block_ `null`: Block Object +- _block_ `WPBlock`: Block Object _Returns_ @@ -561,11 +561,11 @@ in the codebase. _Parameters_ -- _icon_ `null`: Render behavior of a block type icon; one of a Dashicon slug, an element, or a component. +- _icon_ `WPBlockTypeIconRender`: Render behavior of a block type icon; one of a Dashicon slug, an element, or a component. _Returns_ -- `null`: Object describing the icon. +- `WPBlockTypeIconDescriptor`: Object describing the icon. # **parse** @@ -645,7 +645,7 @@ _Parameters_ _Returns_ -- `?WPBlockType`: The block, if it has been successfully registered; otherwise `undefined`. +- `?WPBlock`: The block, if it has been successfully registered; otherwise `undefined`. # **serialize** @@ -750,7 +750,7 @@ _Parameters_ _Returns_ -- `?WPBlockType`: The previous block value, if it has been successfully unregistered; otherwise `undefined`. +- `?WPBlock`: The previous block value, if it has been successfully unregistered; otherwise `undefined`. # **updateCategory** @@ -768,7 +768,7 @@ wrapped component. _Returns_ -- `null`: Enhanced component with injected BlockContent as prop. +- `WPComponent`: Enhanced component with injected BlockContent as prop. diff --git a/packages/blocks/src/api/children.js b/packages/blocks/src/api/children.js index eff87d18466baa..7cf70d2da78151 100644 --- a/packages/blocks/src/api/children.js +++ b/packages/blocks/src/api/children.js @@ -16,7 +16,7 @@ import * as node from './node'; /** * A representation of a block's rich text value. * - * @typedef {import('./node').WPBlockNode[]} WPBlockChildren + * @typedef {WPBlockNode[]} WPBlockChildren */ /** @@ -24,7 +24,7 @@ import * as node from './node'; * * @param {WPBlockChildren} children Block children object to convert. * - * @return {import('@wordpress/element').WPElement} A serialize-capable element. + * @return {WPElement} A serialize-capable element. */ export function getSerializeCapableElement( children ) { // The fact that block children are compatible with the element serializer is @@ -41,7 +41,7 @@ export function getSerializeCapableElement( children ) { * * @param {WPBlockChildren} children Block children object to convert. * - * @return {Array} An array of individual block nodes. + * @return {Array} An array of individual block nodes. */ function getChildrenArray( children ) { // The fact that block children are compatible with the element serializer diff --git a/packages/blocks/src/api/parser.js b/packages/blocks/src/api/parser.js index 0b357e7f1272a7..6300eac329f153 100644 --- a/packages/blocks/src/api/parser.js +++ b/packages/blocks/src/api/parser.js @@ -296,11 +296,11 @@ export function getBlockAttributes( blockTypeOrName, innerHTML, attributes = {} * deprecated migrations applied, or the original block if it was both valid * and no eligible migrations exist. * - * @param {import('./registration').WPBlockType} block Original block object. - * @param {Object} parsedAttributes Attributes as parsed from the initial - * block markup. + * @param {WPBlock} block Original block object. + * @param {Object} parsedAttributes Attributes as parsed from the initial + * block markup. * - * @return {import('./registration').WPBlockType} Migrated block object. + * @return {WPBlock} Migrated block object. */ export function getMigratedBlock( block, parsedAttributes ) { const blockType = getBlockType( block.name ); diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js index b95f7bc8f3a668..0d3dd7827680ec 100644 --- a/packages/blocks/src/api/registration.js +++ b/packages/blocks/src/api/registration.js @@ -28,7 +28,7 @@ import { DEPRECATED_ENTRY_KEYS } from './constants'; * Render behavior of a block type icon; one of a Dashicon slug, an element, * or a component. * - * @typedef {(string|import('@wordpress/element').WPElement|import('@wordpress/element').WPComponent)} WPBlockTypeIconRender + * @typedef {(string|WPElement|WPComponent)} WPBlockTypeIconRender * * @see https://developer.wordpress.org/resource/dashicons/ */ @@ -60,23 +60,23 @@ import { DEPRECATED_ENTRY_KEYS } from './constants'; /** * Defined behavior of a block type. * - * @typedef {Object} WPBlockType - * - * @property {string} name Block type's namespaced name. - * @property {string} title Human-readable block type label. - * @property {string} category Block type category classification, - * used in search interfaces to arrange - * block types by category. - * @property {WPBlockTypeIcon} [icon] Block type icon. - * @property {string[]} [keywords] Additional keywords to produce block - * type as result in search interfaces. - * @property {Object} [attributes] Block type attributes. - * @property {import('@wordpress/element').WPComponent} [save] Optional component describing - * serialized markup structure of a - * block type. - * @property {import('@wordpress/element').WPComponent} edit Component rendering an element to - * manipulate the attributes of a block - * in the context of an editor. + * @typedef {Object} WPBlock + * + * @property {string} name Block type's namespaced name. + * @property {string} title Human-readable block type label. + * @property {string} category Block type category classification, + * used in search interfaces to arrange + * block types by category. + * @property {WPBlockTypeIcon} [icon] Block type icon. + * @property {string[]} [keywords] Additional keywords to produce block + * type as result in search interfaces. + * @property {Object} [attributes] Block type attributes. + * @property {WPComponent} [save] Optional component describing + * serialized markup structure of a + * block type. + * @property {WPComponent} edit Component rendering an element to + * manipulate the attributes of a block + * in the context of an editor. */ /** @@ -113,8 +113,8 @@ export function unstable__bootstrapServerSideBlockDefinitions( definitions ) { / * @param {string} name Block name. * @param {Object} settings Block settings. * - * @return {?WPBlockType} The block, if it has been successfully registered; - * otherwise `undefined`. + * @return {?WPBlock} The block, if it has been successfully registered; + * otherwise `undefined`. */ export function registerBlockType( name, settings ) { settings = { @@ -233,8 +233,8 @@ export function registerBlockType( name, settings ) { * * @param {string} name Block name. * - * @return {?WPBlockType} The previous block value, if it has been successfully - * unregistered; otherwise `undefined`. + * @return {?WPBlock} The previous block value, if it has been successfully + * unregistered; otherwise `undefined`. */ export function unregisterBlockType( name ) { const oldBlock = select( 'core/blocks' ).getBlockType( name ); diff --git a/packages/blocks/src/api/serializer.js b/packages/blocks/src/api/serializer.js index a392fafd32d422..d2dfbcab2d672b 100644 --- a/packages/blocks/src/api/serializer.js +++ b/packages/blocks/src/api/serializer.js @@ -85,9 +85,9 @@ export function getSaveElement( blockTypeOrName, attributes, innerBlocks = [] ) /** * Filters the props applied to the block save result element. * - * @param {Object} props Props applied to save element. - * @param {import('./registration').WPBlockType} blockType Block type definition. - * @param {Object} attributes Block attributes. + * @param {Object} props Props applied to save element. + * @param {WPBlock} blockType Block type definition. + * @param {Object} attributes Block attributes. */ const props = applyFilters( 'blocks.getSaveContent.extraProps', @@ -104,9 +104,9 @@ export function getSaveElement( blockTypeOrName, attributes, innerBlocks = [] ) /** * Filters the save result of a block during serialization. * - * @param {import('@wordpress/element').WPElement} element Block save result. - * @param {import('./registration').WPBlockType} blockType Block type definition. - * @param {Object} attributes Block attributes. + * @param {WPElement} element Block save result. + * @param {WPBlock} blockType Block type definition. + * @param {Object} attributes Block attributes. */ element = applyFilters( 'blocks.getSaveElement', element, blockType, attributes ); diff --git a/packages/blocks/src/api/utils.js b/packages/blocks/src/api/utils.js index 5d66227aa2d239..99dc98b5c3204b 100644 --- a/packages/blocks/src/api/utils.js +++ b/packages/blocks/src/api/utils.js @@ -28,7 +28,7 @@ const ICON_COLORS = [ '#191e23', '#f8f9f9' ]; * and its attributes are equal to the default attributes * which means the block is unmodified. * - * @param {import('./registration').WPBlockType} block Block Object + * @param {WPBlock} block Block Object * * @return {boolean} Whether the block is an unmodified default block */ @@ -77,11 +77,11 @@ export function isValidIcon( icon ) { * and returns a new icon object that is normalized so we can rely on just on possible icon structure * in the codebase. * - * @param {import('./registration').WPBlockTypeIconRender} icon Render behavior of a block type icon; - * one of a Dashicon slug, an element, or a - * component. + * @param {WPBlockTypeIconRender} icon Render behavior of a block type icon; + * one of a Dashicon slug, an element, or a + * component. * - * @return {import('./registration').WPBlockTypeIconDescriptor} Object describing the icon. + * @return {WPBlockTypeIconDescriptor} Object describing the icon. */ export function normalizeIconObject( icon ) { if ( isValidIcon( icon ) ) { diff --git a/packages/blocks/src/block-content-provider/index.js b/packages/blocks/src/block-content-provider/index.js index e9343ad08d63aa..96b9a4d31bcd1b 100644 --- a/packages/blocks/src/block-content-provider/index.js +++ b/packages/blocks/src/block-content-provider/index.js @@ -26,7 +26,7 @@ const { Consumer, Provider } = createContext( () => {} ); * * ``` * - * @return {import('@wordpress/element').WPComponent} Element with BlockContent injected via context. + * @return {WPComponent} Element with BlockContent injected via context. */ const BlockContentProvider = ( { children, innerBlocks } ) => { const BlockContent = () => { @@ -48,7 +48,7 @@ const BlockContentProvider = ( { children, innerBlocks } ) => { * A Higher Order Component used to inject BlockContent using context to the * wrapped component. * - * @return {import('@wordpress/element').WPComponent} Enhanced component with injected BlockContent as prop. + * @return {WPComponent} Enhanced component with injected BlockContent as prop. */ export const withBlockContentContext = createHigherOrderComponent( ( OriginalComponent ) => { return ( props ) => ( diff --git a/packages/components/src/autocomplete/index.js b/packages/components/src/autocomplete/index.js index 34c0ed239df878..b12f97b30367ba 100644 --- a/packages/components/src/autocomplete/index.js +++ b/packages/components/src/autocomplete/index.js @@ -77,7 +77,7 @@ import withSpokenMessages from '../higher-order/with-spoken-messages'; /** * A completion value. * - * @typedef {(string|import('@wordpress/element').WPElement|Object)} OptionCompletionValue + * @typedef {(string|WPElement|Object)} OptionCompletionValue */ /** @@ -91,7 +91,7 @@ import withSpokenMessages from '../higher-order/with-spoken-messages'; */ /** - * @typedef {Object} Completer + * @typedef {Object} WPCompleter * @property {string} name a way to identify a completer, useful for selective overriding. * @property {?string} className A class to apply to the popup menu. * @property {string} triggerPrefix the prefix that will display the menu. @@ -232,8 +232,8 @@ export class Autocomplete extends Component { /** * Load options for an autocompleter. * - * @param {Completer} completer The autocompleter. - * @param {string} query The query, if any. + * @param {WPCompleter} completer The autocompleter. + * @param {string} query The query, if any. */ loadOptions( completer, query ) { const { options } = completer; diff --git a/packages/components/src/date-time/date.js b/packages/components/src/date-time/date.js index 19c701ffbf74a9..7b1accff50227d 100644 --- a/packages/components/src/date-time/date.js +++ b/packages/components/src/date-time/date.js @@ -65,7 +65,7 @@ class DatePicker extends Component { * object representing now. If a null value is passed, return a null value. * * @param {?string} currentDate Date representing the currently selected date or null to signify no selection. - * @return {?import('moment').Moment} Moment object for selected date or null. + * @return {?moment.Moment} Moment object for selected date or null. */ getMomentDate( currentDate ) { if ( null === currentDate ) { diff --git a/packages/components/src/higher-order/with-focus-return/index.js b/packages/components/src/higher-order/with-focus-return/index.js index f193b348b99010..6a411ad909af9f 100644 --- a/packages/components/src/higher-order/with-focus-return/index.js +++ b/packages/components/src/higher-order/with-focus-return/index.js @@ -35,12 +35,12 @@ function isComponentLike( object ) { * reference to the current active element so we know where to restore focus * when the component is unmounted. * - * @param {(import('@wordpress/element').WPComponent|Object)} options The component to be enhanced with - * focus return behavior, or an object - * describing the component and the - * focus return characteristics. + * @param {(WPComponent|Object)} options The component to be enhanced with + * focus return behavior, or an object + * describing the component and the + * focus return characteristics. * - * @return {import('@wordpress/element').WPComponent} Component with the focus restauration behaviour. + * @return {WPComponent} Component with the focus restauration behaviour. */ function withFocusReturn( options ) { // Normalize as overloaded form `withFocusReturn( options )( Component )` diff --git a/packages/components/src/higher-order/with-notices/index.js b/packages/components/src/higher-order/with-notices/index.js index aa5710baad7623..9097728b2921a8 100644 --- a/packages/components/src/higher-order/with-notices/index.js +++ b/packages/components/src/higher-order/with-notices/index.js @@ -17,9 +17,9 @@ import NoticeList from '../../notice/list'; /** * Override the default edit UI to include notices if supported. * - * @param {import('@wordpress/element').WPComponent} OriginalComponent Original component. + * @param {WPComponent} OriginalComponent Original component. * - * @return {import('@wordpress/element').WPComponent} Wrapped component. + * @return {WPComponent} Wrapped component. */ export default createHigherOrderComponent( ( OriginalComponent ) => { return class WrappedBlockEdit extends Component { diff --git a/packages/components/src/higher-order/with-spoken-messages/index.js b/packages/components/src/higher-order/with-spoken-messages/index.js index 389e4c2cffcfa4..406d10bf0a245a 100644 --- a/packages/components/src/higher-order/with-spoken-messages/index.js +++ b/packages/components/src/higher-order/with-spoken-messages/index.js @@ -14,9 +14,9 @@ import { createHigherOrderComponent } from '@wordpress/compose'; * A Higher Order Component used to be provide a unique instance ID by * component. * - * @param {import('@wordpress/element').WPComponent} WrappedComponent The wrapped component. + * @param {WPComponent} WrappedComponent The wrapped component. * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ export default createHigherOrderComponent( ( WrappedComponent ) => { return class extends Component { diff --git a/packages/components/src/menu-item/index.js b/packages/components/src/menu-item/index.js index 76ffa2e5ad1895..3227659e6d10a8 100644 --- a/packages/components/src/menu-item/index.js +++ b/packages/components/src/menu-item/index.js @@ -18,7 +18,7 @@ import IconButton from '../icon-button'; /** * Renders a generic menu item for use inside the more menu. * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ export function MenuItem( { children, diff --git a/packages/components/src/modal/frame.js b/packages/components/src/modal/frame.js index 95cd509eb3ed26..286171a06e0ca2 100644 --- a/packages/components/src/modal/frame.js +++ b/packages/components/src/modal/frame.js @@ -101,7 +101,7 @@ class ModalFrame extends Component { /** * Renders the modal frame element. * - * @return {import('@wordpress/element').WPElement} The modal frame element. + * @return {WPElement} The modal frame element. */ render() { const { diff --git a/packages/components/src/modal/index.js b/packages/components/src/modal/index.js index dd8b0bef8f19ef..f4a64c289b4e7d 100644 --- a/packages/components/src/modal/index.js +++ b/packages/components/src/modal/index.js @@ -98,7 +98,7 @@ class Modal extends Component { /** * Renders the modal. * - * @return {import('@wordpress/element').WPElement} The modal element. + * @return {WPElement} The modal element. */ render() { const { diff --git a/packages/components/src/scroll-lock/index.js b/packages/components/src/scroll-lock/index.js index 07e62cb18a5227..1d6255d8c12ef9 100644 --- a/packages/components/src/scroll-lock/index.js +++ b/packages/components/src/scroll-lock/index.js @@ -12,7 +12,7 @@ import { Component } from '@wordpress/element'; * @param {Object} args Keyword args. * @param {HTMLDocument} args.htmlDocument The document to lock the scroll for. * @param {string} args.className The name of the class used to lock scrolling. - * @return {import('@wordpress/element').WPComponent} The bound ScrollLock component. + * @return {WPComponent} The bound ScrollLock component. */ export function createScrollLockComponent( { htmlDocument = document, diff --git a/packages/components/src/toolbar/index.js b/packages/components/src/toolbar/index.js index 8a795f98e2b5bf..bf9237eed1b624 100644 --- a/packages/components/src/toolbar/index.js +++ b/packages/components/src/toolbar/index.js @@ -34,13 +34,13 @@ import ToolbarContainer from './toolbar-container'; * Either `controls` or `children` is required, otherwise this components * renders nothing. * - * @param {Object} props - * @param {Array} [props.controls] The controls to render in this toolbar. - * @param {import('@wordpress/element').WPElement} [props.children] Any other things to render inside the - * toolbar besides the controls. - * @param {string} [props.className] Class to set on the container div. + * @param {Object} props + * @param {Array} [props.controls] The controls to render in this toolbar. + * @param {WPElement} [props.children] Any other things to render inside the + * toolbar besides the controls. + * @param {string} [props.className] Class to set on the container div. * - * @return {import('@wordpress/element').WPComponent} The rendered component. + * @return {WPComponent} The rendered component. */ function Toolbar( { controls = [], children, className, isCollapsed, icon, label, ...otherProps } ) { if ( diff --git a/packages/compose/README.md b/packages/compose/README.md index 9c69fed546567a..7fcf12e07a7293 100644 --- a/packages/compose/README.md +++ b/packages/compose/README.md @@ -90,7 +90,7 @@ _Parameters_ _Returns_ -- `null`: Component class with generated display name assigned. +- `WPComponent`: Component class with generated display name assigned. # **ifCondition** @@ -117,7 +117,7 @@ _Parameters_ _Returns_ -- `null`: Component class with generated display name assigned. +- `WPComponent`: Component class with generated display name assigned. # **useMediaQuery** @@ -163,11 +163,11 @@ component. _Parameters_ -- _WrappedComponent_ `null`: The wrapped component. +- _WrappedComponent_ `WPComponent`: The wrapped component. _Returns_ -- `null`: Component with an instanceId prop. +- `WPComponent`: Component with an instanceId prop. # **withSafeTimeout** @@ -176,11 +176,11 @@ that ought to be bound to a component's lifecycle. _Parameters_ -- _OriginalComponent_ `null`: Component requiring setTimeout +- _OriginalComponent_ `WPComponent`: Component requiring setTimeout _Returns_ -- `null`: Wrapped component. +- `WPComponent`: Wrapped component. # **withState** @@ -193,7 +193,7 @@ _Parameters_ _Returns_ -- `null`: Wrapped component. +- `WPComponent`: Wrapped component. diff --git a/packages/compose/src/higher-order/pure/index.js b/packages/compose/src/higher-order/pure/index.js index d9551f5582e2ad..e721fbb7964796 100644 --- a/packages/compose/src/higher-order/pure/index.js +++ b/packages/compose/src/higher-order/pure/index.js @@ -18,7 +18,7 @@ import createHigherOrderComponent from '../../utils/create-higher-order-componen * @param {string} modifierName Seed name from which to * generated display name. * - * @return {import('@wordpress/element').WPComponent} Component class with generated display name assigned. + * @return {WPComponent} Component class with generated display name assigned. */ const pure = createHigherOrderComponent( ( Wrapped ) => { if ( Wrapped.prototype instanceof Component ) { diff --git a/packages/compose/src/higher-order/with-instance-id/index.js b/packages/compose/src/higher-order/with-instance-id/index.js index cb8cbfb42ecf49..960c6997e8671f 100644 --- a/packages/compose/src/higher-order/with-instance-id/index.js +++ b/packages/compose/src/higher-order/with-instance-id/index.js @@ -12,9 +12,9 @@ import createHigherOrderComponent from '../../utils/create-higher-order-componen * A Higher Order Component used to be provide a unique instance ID by * component. * - * @param {import('@wordpress/element').WPComponent} WrappedComponent The wrapped component. + * @param {WPComponent} WrappedComponent The wrapped component. * - * @return {import('@wordpress/element').WPComponent} Component with an instanceId prop. + * @return {WPComponent} Component with an instanceId prop. */ export default createHigherOrderComponent( ( WrappedComponent ) => { let instances = 0; diff --git a/packages/compose/src/higher-order/with-safe-timeout/index.js b/packages/compose/src/higher-order/with-safe-timeout/index.js index 5a0b1cfec3a574..43d4e9e780d5b7 100644 --- a/packages/compose/src/higher-order/with-safe-timeout/index.js +++ b/packages/compose/src/higher-order/with-safe-timeout/index.js @@ -17,9 +17,9 @@ import createHigherOrderComponent from '../../utils/create-higher-order-componen * A higher-order component used to provide and manage delayed function calls * that ought to be bound to a component's lifecycle. * - * @param {import('@wordpress/element').WPComponent} OriginalComponent Component requiring setTimeout + * @param {WPComponent} OriginalComponent Component requiring setTimeout * - * @return {import('@wordpress/element').WPComponent} Wrapped component. + * @return {WPComponent} Wrapped component. */ const withSafeTimeout = createHigherOrderComponent( ( OriginalComponent ) => { diff --git a/packages/compose/src/higher-order/with-state/index.js b/packages/compose/src/higher-order/with-state/index.js index 7f59410853ac64..02db9392b39631 100644 --- a/packages/compose/src/higher-order/with-state/index.js +++ b/packages/compose/src/higher-order/with-state/index.js @@ -14,7 +14,7 @@ import createHigherOrderComponent from '../../utils/create-higher-order-componen * * @param {?Object} initialState Optional initial state of the component. * - * @return {import('@wordpress/element').WPComponent} Wrapped component. + * @return {WPComponent} Wrapped component. */ export default function withState( initialState = {} ) { return createHigherOrderComponent( ( OriginalComponent ) => { diff --git a/packages/compose/src/utils/create-higher-order-component/index.js b/packages/compose/src/utils/create-higher-order-component/index.js index 4bac128095b936..448193468c94eb 100644 --- a/packages/compose/src/utils/create-higher-order-component/index.js +++ b/packages/compose/src/utils/create-higher-order-component/index.js @@ -12,7 +12,7 @@ import { camelCase, upperFirst } from 'lodash'; * @param {string} modifierName Seed name from which to * generated display name. * - * @return {import('@wordpress/element').WPComponent} Component class with generated display name assigned. + * @return {WPComponent} Component class with generated display name assigned. */ function createHigherOrderComponent( mapComponentToEnhancedComponent, modifierName ) { return ( OriginalComponent ) => { diff --git a/packages/data/README.md b/packages/data/README.md index e3f3d9d50e50e1..ca3c5fcab29bba 100644 --- a/packages/data/README.md +++ b/packages/data/README.md @@ -693,7 +693,7 @@ _Parameters_ _Returns_ -- `null`: Enhanced component with merged dispatcher props. +- `WPComponent`: Enhanced component with merged dispatcher props. # **withRegistry** @@ -702,11 +702,11 @@ registry context passed as its `registry` prop. _Parameters_ -- _OriginalComponent_ `null`: Original component. +- _OriginalComponent_ `WPComponent`: Original component. _Returns_ -- `null`: Enhanced component. +- `WPComponent`: Enhanced component. # **withSelect** @@ -750,7 +750,7 @@ _Parameters_ _Returns_ -- `null`: Enhanced component with merged state data props. +- `WPComponent`: Enhanced component with merged state data props. diff --git a/packages/data/src/components/with-dispatch/index.js b/packages/data/src/components/with-dispatch/index.js index 9f613c7b9d0f54..3e6c2194dec5f4 100644 --- a/packages/data/src/components/with-dispatch/index.js +++ b/packages/data/src/components/with-dispatch/index.js @@ -85,7 +85,7 @@ import { useDispatchWithMap } from '../use-dispatch'; * returns an object with the same keys. For example, it should not contain * conditions under which a different value would be returned. * - * @return {import('@wordpress/element').WPComponent} Enhanced component with merged dispatcher props. + * @return {WPComponent} Enhanced component with merged dispatcher props. */ const withDispatch = ( mapDispatchToProps ) => createHigherOrderComponent( ( WrappedComponent ) => ( ownProps ) => { diff --git a/packages/data/src/components/with-registry/index.js b/packages/data/src/components/with-registry/index.js index b27c1d278ad242..32d1c8e1a40fd5 100644 --- a/packages/data/src/components/with-registry/index.js +++ b/packages/data/src/components/with-registry/index.js @@ -12,9 +12,9 @@ import { RegistryConsumer } from '../registry-provider'; * Higher-order component which renders the original component with the current * registry context passed as its `registry` prop. * - * @param {import('@wordpress/element').WPComponent} OriginalComponent Original component. + * @param {WPComponent} OriginalComponent Original component. * - * @return {import('@wordpress/element').WPComponent} Enhanced component. + * @return {WPComponent} Enhanced component. */ const withRegistry = createHigherOrderComponent( ( OriginalComponent ) => ( props ) => ( diff --git a/packages/data/src/components/with-select/index.js b/packages/data/src/components/with-select/index.js index feee44ea313c9a..aeb86761494e44 100644 --- a/packages/data/src/components/with-select/index.js +++ b/packages/data/src/components/with-select/index.js @@ -45,7 +45,7 @@ import useSelect from '../use-select'; * component and update automatically if the price of a hammer ever changes in * the store. * - * @return {import('@wordpress/element').WPComponent} Enhanced component with merged state data props. + * @return {WPComponent} Enhanced component with merged state data props. */ const withSelect = ( mapSelectToProps ) => createHigherOrderComponent( ( WrappedComponent ) => pure( diff --git a/packages/data/src/factory.js b/packages/data/src/factory.js index e6e867fecdcb8d..bdc2f1519e60e5 100644 --- a/packages/data/src/factory.js +++ b/packages/data/src/factory.js @@ -3,10 +3,6 @@ */ import defaultRegistry from './default-registry'; -/** - * @typedef {import('./registry').WPDataRegistry} WPDataRegistry - */ - /** * Mark a selector as a registry selector. * @@ -29,7 +25,7 @@ export function createRegistrySelector( registrySelector ) { * Registry on which to call `select`, stubbed for non-standard usage to * use the default registry. * - * @type {import('./registry').WPDataRegistry} + * @type {WPDataRegistry} */ selector.registry = defaultRegistry; diff --git a/packages/data/src/namespace-store/index.js b/packages/data/src/namespace-store/index.js index 3953a753928590..bc41587569bbba 100644 --- a/packages/data/src/namespace-store/index.js +++ b/packages/data/src/namespace-store/index.js @@ -24,17 +24,17 @@ import * as metadataSelectors from './metadata/selectors'; import * as metadataActions from './metadata/actions'; /** - * @typedef {import('../registry').WPDataRegistry} WPDataRegistry + * @typedef {WPDataRegistry} WPDataRegistry */ /** * Creates a namespace object with a store derived from the reducer given. * - * @param {string} key Unique namespace identifier. - * @param {Object} options Registered store options, with properties - * describing reducer, actions, selectors, and - * resolvers. - * @param {import('../registry').WPDataRegistry} registry Registry reference. + * @param {string} key Unique namespace identifier. + * @param {Object} options Registered store options, with properties + * describing reducer, actions, selectors, and + * resolvers. + * @param {WPDataRegistry} registry Registry reference. * * @return {Object} Store Object. */ @@ -104,11 +104,11 @@ export default function createNamespace( key, options, registry ) { /** * Creates a redux store for a namespace. * - * @param {string} key Unique namespace identifier. - * @param {Object} options Registered store options, with properties - * describing reducer, actions, selectors, and - * resolvers. - * @param {import('../registry').WPDataRegistry} registry Registry reference. + * @param {string} key Unique namespace identifier. + * @param {Object} options Registered store options, with properties + * describing reducer, actions, selectors, and + * resolvers. + * @param {WPDataRegistry} registry Registry reference. * * @return {Object} Newly created redux store. */ diff --git a/packages/data/src/plugins/persistence/index.js b/packages/data/src/plugins/persistence/index.js index e5461a4204d724..871a7e56133594 100644 --- a/packages/data/src/plugins/persistence/index.js +++ b/packages/data/src/plugins/persistence/index.js @@ -112,10 +112,10 @@ export function createPersistenceInterface( options ) { /** * Data plugin to persist store state into a single storage key. * - * @param {import('../../registry').WPDataRegistry} registry Data registry. - * @param {?WPDataPersistencePluginOptions} pluginOptions Plugin options. + * @param {WPDataRegistry} registry Data registry. + * @param {?WPDataPersistencePluginOptions} pluginOptions Plugin options. * - * @return {import('../../registry').WPDataPlugin} Data plugin. + * @return {WPDataPlugin} Data plugin. */ const persistencePlugin = function( registry, pluginOptions ) { const persistence = createPersistenceInterface( pluginOptions ); diff --git a/packages/data/src/resolvers-cache-middleware.js b/packages/data/src/resolvers-cache-middleware.js index 0783f264c91423..e7e0a2ae7c6201 100644 --- a/packages/data/src/resolvers-cache-middleware.js +++ b/packages/data/src/resolvers-cache-middleware.js @@ -6,10 +6,10 @@ import { get } from 'lodash'; /** * Creates a middleware handling resolvers cache invalidation. * - * @param {import('./registry').WPDataRegistry} registry The registry reference for which to create - * the middleware. - * @param {string} reducerKey The namespace for which to create the - * middleware. + * @param {WPDataRegistry} registry The registry reference for which to create + * the middleware. + * @param {string} reducerKey The namespace for which to create the + * middleware. * * @return {Function} Middleware function. */ diff --git a/packages/date/README.md b/packages/date/README.md index 8ee9d3fdf0a74d..96cbbba1b7239d 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_ `null`: Date object or string, parsable by moment.js. +- _dateValue_ `(Date|string|moment.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_ `null`: Date object or string, parsable by moment.js. +- _dateValue_ `(Date|string|moment.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_ `null`: Date object or string, parsable by moment.js. +- _dateValue_ `(Date|string|moment.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_ `null`: Date object or string, parsable by moment.js. +- _dateValue_ `(Date|string|moment.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 560fd5605ba9d8..4537ec47284749 100644 --- a/packages/date/src/index.js +++ b/packages/date/src/index.js @@ -145,7 +145,7 @@ const formatMap = { /** * Gets the ordinal suffix. * - * @param {import('moment').Moment} momentDate Moment instance. + * @param {moment.Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -160,7 +160,7 @@ const formatMap = { /** * Gets the day of the year (zero-indexed). * - * @param {import('moment').Moment} momentDate Moment instance. + * @param {moment.Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -180,7 +180,7 @@ const formatMap = { /** * Gets the days in the month. * - * @param {import('moment').Moment} momentDate Moment instance. + * @param {moment.Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -192,7 +192,7 @@ const formatMap = { /** * Gets whether the current year is a leap year. * - * @param {import('moment').Moment} momentDate Moment instance. + * @param {moment.Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -209,7 +209,7 @@ const formatMap = { /** * Gets the current time in Swatch Internet Time (.beats). * - * @param {import('moment').Moment} momentDate Moment instance. + * @param {moment.Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -240,7 +240,7 @@ const formatMap = { /** * Gets whether the timezone is in DST currently. * - * @param {import('moment').Moment} momentDate Moment instance. + * @param {moment.Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -253,7 +253,7 @@ const formatMap = { /** * Gets the timezone offset in seconds. * - * @param {import('moment').Moment} momentDate Moment instance. + * @param {moment.Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -273,10 +273,10 @@ const formatMap = { /** * Formats a date. Does not alter the date's timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. - * @param {(Date|string|import('moment').Moment|null)} dateValue Date object or string, - * parsable by moment.js. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|moment.Moment|null)} dateValue Date object or string, + * parsable by moment.js. * * @return {string} Formatted date. */ @@ -314,10 +314,10 @@ export function format( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `date()` in PHP), in the site's timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. - * @param {(Date|string|import('moment').Moment|null)} dateValue Date object or string, - * parsable by moment.js. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|moment.Moment|null)} dateValue Date object or string, + * parsable by moment.js. * * @return {string} Formatted date. */ @@ -330,10 +330,10 @@ export function date( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `date()` in PHP), in the UTC timezone. * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. - * @param {(Date|string|import('moment').Moment|null)} dateValue Date object or string, - * parsable by moment.js. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|moment.Moment|null)} dateValue Date object or string, + * parsable by moment.js. * * @return {string} Formatted date. */ @@ -345,12 +345,12 @@ export function gmdate( dateFormat, dateValue = new Date() ) { /** * Formats a date (like `date_i18n()` in PHP). * - * @param {string} dateFormat PHP-style formatting string. - * See php.net/date. - * @param {(Date|string|import('moment').Moment|null)} dateValue Date object or string, - * parsable by moment.js. - * @param {boolean} gmt True for GMT/UTC, false for - * site's timezone. + * @param {string} dateFormat PHP-style formatting string. + * See php.net/date. + * @param {(Date|string|moment.Moment|null)} dateValue Date object or string, + * parsable by moment.js. + * @param {boolean} gmt True for GMT/UTC, false for + * site's timezone. * * @return {string} Formatted date. */ diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md index a90533b68ae703..e01082057a82a8 100644 --- a/packages/e2e-test-utils/README.md +++ b/packages/e2e-test-utils/README.md @@ -191,7 +191,7 @@ _Parameters_ _Returns_ -- `null`: Object that represents an in-page DOM element. +- `?puppeteer.ElementHandle`: Object that represents an in-page DOM element. # **findSidebarPanelWithTitle** @@ -203,7 +203,7 @@ _Parameters_ _Returns_ -- `null`: Object that represents an in-page DOM element. +- `?puppeteer.ElementHandle`: 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 598995828661c4..f8f2976de67a76 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,7 @@ /** * Callback which automatically accepts dialog. * - * @param {import('puppeteer').Dialog} dialog Dialog object dispatched by page via the 'dialog' event. + * @param {puppeteer.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 f4a5f2f8a98744..55fbf4c91c10f2 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 @@ -8,7 +8,7 @@ import { first } from 'lodash'; * * @param {string} panelTitle The name of sidebar panel. * - * @return {?import('puppeteer').ElementHandle} Object that represents an in-page DOM element. + * @return {?puppeteer.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 4bd283be731db8..2f1436c5b8de23 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 @@ -8,7 +8,7 @@ import { first } from 'lodash'; * * @param {string} panelTitle The name of sidebar panel. * - * @return {?import('puppeteer').ElementHandle} Object that represents an in-page DOM element. + * @return {?puppeteer.ElementHandle} Object that represents an in-page DOM element. */ export async function findSidebarPanelWithTitle( panelTitle ) { const classSelect = ( className ) => `[contains(concat(" ", @class, " "), " ${ className } ")]`; 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 877d1c0dd04aed..ea79e31224e8e0 100644 --- a/packages/e2e-tests/specs/editor/various/adding-blocks.test.js +++ b/packages/e2e-tests/specs/editor/various/adding-blocks.test.js @@ -17,7 +17,7 @@ describe( 'adding blocks', () => { /** * Given a Puppeteer ElementHandle, clicks below its bounding box. * - * @param {import('puppeteer').ElementHandle} elementHandle Element handle. + * @param {puppeteer.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 d460b7a0cd8f1f..505f8cca3ba3a4 100644 --- a/packages/e2e-tests/specs/editor/various/preview.test.js +++ b/packages/e2e-tests/specs/editor/various/preview.test.js @@ -41,7 +41,7 @@ async function openPreviewPage( editorPage ) { * Given a Puppeteer Page instance for a preview window, clicks Preview, and * awaits the window navigation. * - * @param {import('puppeteer').Page} previewPage Page on which to await navigation. + * @param {puppeteer.Page} previewPage Page on which to await navigation. * * @return {Promise} Promise resolving once navigation completes. */ diff --git a/packages/edit-post/README.md b/packages/edit-post/README.md index b6c2e914f8b758..0a9441a55b101f 100644 --- a/packages/edit-post/README.md +++ b/packages/edit-post/README.md @@ -92,13 +92,13 @@ _Parameters_ - _props_ `Object`: Component props. - _props.allowedBlocks_ `[Array]`: An array containing a list of block names for which the item should be shown. If not present, it'll be rendered for any block. If multiple blocks are selected, it'll be shown if and only if all of them are in the whitelist. -- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. +- _props.icon_ `[WPBlockTypeIconRender]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. - _props.label_ `string`: The menu item text. - _props.onClick_ `Function`: Callback function to be executed when the user click the menu item. _Returns_ -- `null`: The component to be rendered. +- `WPComponent`: The component to be rendered. # **PluginDocumentSettingPanel** @@ -149,11 +149,11 @@ _Parameters_ - _props.name_ `[string]`: The machine-friendly name for the panel. - _props.className_ `[string]`: An optional class name added to the row. - _props.title_ `[string]`: The title of the panel -- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. +- _props.icon_ `[WPBlockTypeIconRender]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. _Returns_ -- `null`: The component to be rendered. +- `WPComponent`: The component to be rendered. # **PluginMoreMenuItem** @@ -206,13 +206,13 @@ _Parameters_ - _props_ `Object`: Component properties. - _props.href_ `[string]`: When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. -- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. +- _props.icon_ `[WPBlockTypeIconRender]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. - _props.onClick_ `[Function]`: The callback function to be executed when the user clicks the menu item. - _props.other_ `[...*]`: Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. _Returns_ -- `null`: The component to be rendered. +- `WPComponent`: The component to be rendered. # **PluginPostPublishPanel** @@ -261,11 +261,11 @@ _Parameters_ - _props.className_ `[string]`: An optional class name added to the panel. - _props.title_ `[string]`: Title displayed at the top of the panel. - _props.initialOpen_ `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. -- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. +- _props.icon_ `[WPBlockTypeIconRender]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. _Returns_ -- `null`: The component to be rendered. +- `WPComponent`: The component to be rendered. # **PluginPostStatusInfo** @@ -312,7 +312,7 @@ _Parameters_ _Returns_ -- `null`: The component to be rendered. +- `WPComponent`: The component to be rendered. # **PluginPrePublishPanel** @@ -361,11 +361,11 @@ _Parameters_ - _props.className_ `[string]`: An optional class name added to the panel. - _props.title_ `[string]`: Title displayed at the top of the panel. - _props.initialOpen_ `[boolean]`: Whether to have the panel initially opened. When no title is provided it is always opened. -- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. +- _props.icon_ `[WPBlockTypeIconRender]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. _Returns_ -- `null`: The component to be rendered. +- `WPComponent`: The component to be rendered. # **PluginSidebar** @@ -432,11 +432,11 @@ _Parameters_ - _props.className_ `[string]`: An optional class name added to the sidebar body. - _props.title_ `string`: Title displayed at the top of the sidebar. - _props.isPinnable_ `[boolean]`: Whether to allow to pin sidebar to toolbar. -- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. +- _props.icon_ `[WPBlockTypeIconRender]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. _Returns_ -- `null`: Plugin sidebar component. +- `WPComponent`: Plugin sidebar component. # **PluginSidebarMoreMenuItem** @@ -482,11 +482,11 @@ _Parameters_ - _props_ `Object`: Component props. - _props.target_ `string`: A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. -- _props.icon_ `null`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. +- _props.icon_ `[WPBlockTypeIconRender]`: The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. _Returns_ -- `null`: The component to be rendered. +- `WPComponent`: The component to be rendered. # **reinitializeEditor** diff --git a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js index 881034393fd389..938805e057406b 100644 --- a/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js +++ b/packages/edit-post/src/components/block-settings-menu/plugin-block-settings-menu-item.js @@ -35,7 +35,7 @@ const shouldRenderItem = ( selectedBlocks, allowedBlocks ) => ! Array.isArray( a * * @param {Object} props Component props. * @param {Array} [props.allowedBlocks] An array containing a list of block names for which the item should be shown. If not present, it'll be rendered for any block. If multiple blocks are selected, it'll be shown if and only if all of them are in the whitelist. - * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. + * @param {WPBlockTypeIconRender} [props.icon] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element. * @param {string} props.label The menu item text. * @param {Function} props.onClick Callback function to be executed when the user click the menu item. * @@ -81,7 +81,7 @@ const shouldRenderItem = ( selectedBlocks, allowedBlocks ) => ! Array.isArray( a * ); * ``` * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ const PluginBlockSettingsMenuItem = ( { allowedBlocks, icon, label, onClick, small, role } ) => ( diff --git a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js index 9597af6c328e5f..08a5bef83b35eb 100644 --- a/packages/edit-post/src/components/header/plugin-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-more-menu-item/index.js @@ -32,7 +32,7 @@ const PluginMoreMenuItem = ( { onClick = noop, ...props } ) => ( * * @param {Object} props Component properties. * @param {string} [props.href] When `href` is provided then the menu item is represented as an anchor rather than button. It corresponds to the `href` attribute of the anchor. - * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. + * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. * @param {Function} [props.onClick=noop] The callback function to be executed when the user clicks the menu item. * @param {...*} [props.other] Any additional props are passed through to the underlying [MenuItem](/packages/components/src/menu-item/README.md) component. * @@ -78,7 +78,7 @@ const PluginMoreMenuItem = ( { onClick = noop, ...props } ) => ( * ); * ``` * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ export default compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js index ea0167b4ce2307..c1f4ff42ae98aa 100644 --- a/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js +++ b/packages/edit-post/src/components/header/plugin-sidebar-more-menu-item/index.js @@ -28,7 +28,7 @@ const PluginSidebarMoreMenuItem = ( { children, icon, isSelected, onClick } ) => * * @param {Object} props Component props. * @param {string} props.target A string identifying the target sidebar you wish to be activated by this menu item. Must be the same as the `name` prop you have given to that sidebar. - * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. + * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered to the left of the menu item label. * * @example ES5 * ```js @@ -64,7 +64,7 @@ const PluginSidebarMoreMenuItem = ( { children, icon, isSelected, onClick } ) => * ); * ``` * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ export default compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js index bdc118376efa05..62a651c7f0c24e 100644 --- a/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-document-setting-panel/index.js @@ -48,7 +48,7 @@ const PluginDocumentSettingFill = ( { isEnabled, panelName, opened, onToggle, cl * @param {string} [props.name] The machine-friendly name for the panel. * @param {string} [props.className] An optional class name added to the row. * @param {string} [props.title] The title of the panel - * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. + * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example ES5 * ```js @@ -89,7 +89,7 @@ const PluginDocumentSettingFill = ( { isEnabled, panelName, opened, onToggle, cl * registerPlugin( 'document-setting-test', { render: MyDocumentSettingTest } ); * ``` * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ const PluginDocumentSettingPanel = compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js index e050d1f0df8505..b1c53372857023 100644 --- a/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-post-publish-panel/index.js @@ -27,7 +27,7 @@ const PluginPostPublishPanelFill = ( { children, className, title, initialOpen = * @param {string} [props.className] An optional class name added to the panel. * @param {string} [props.title] Title displayed at the top of the panel. * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. When no title is provided it is always opened. - * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. + * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example ES5 * ```js @@ -65,7 +65,7 @@ const PluginPostPublishPanelFill = ( { children, className, title, initialOpen = * ); * ``` * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ const PluginPostPublishPanel = compose( diff --git a/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js b/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js index cbedd5f7c88c8f..2d149639130eda 100644 --- a/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-post-status-info/index.js @@ -49,7 +49,7 @@ export const { Fill, Slot } = createSlotFill( 'PluginPostStatusInfo' ); * ); * ``` * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ const PluginPostStatusInfo = ( { children, className } ) => ( diff --git a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js index 54d6f1c944b442..13863b24f16d50 100644 --- a/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-pre-publish-panel/index.js @@ -23,14 +23,14 @@ const PluginPrePublishPanelFill = ( { children, className, title, initialOpen = * Renders provided content to the pre-publish side panel in the publish flow * (side panel that opens when a user first pushes "Publish" from the main editor). * - * @param {Object} props Component props. - * @param {string} [props.className] An optional class name added to the panel. - * @param {string} [props.title] Title displayed at the top of the panel. - * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. - * When no title is provided it is always opened. - * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) - * icon slug string, or an SVG WP element, to be rendered when - * the sidebar is pinned to toolbar. + * @param {Object} props Component props. + * @param {string} [props.className] An optional class name added to the panel. + * @param {string} [props.title] Title displayed at the top of the panel. + * @param {boolean} [props.initialOpen=false] Whether to have the panel initially opened. + * When no title is provided it is always opened. + * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) + * icon slug string, or an SVG WP element, to be rendered when + * the sidebar is pinned to toolbar. * * @example ES5 * ```js @@ -68,7 +68,7 @@ const PluginPrePublishPanelFill = ( { children, className, title, initialOpen = * ); * ``` * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ const PluginPrePublishPanel = compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js b/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js index e59e6eb96d0574..7c03f172b009fb 100644 --- a/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js +++ b/packages/edit-post/src/components/sidebar/plugin-sidebar/index.js @@ -82,7 +82,7 @@ function PluginSidebar( props ) { * @param {string} [props.className] An optional class name added to the sidebar body. * @param {string} props.title Title displayed at the top of the sidebar. * @param {boolean} [props.isPinnable=true] Whether to allow to pin sidebar to toolbar. - * @param {import('@wordpress/blocks').WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. + * @param {WPBlockTypeIconRender} [props.icon=inherits from the plugin] The [Dashicon](https://developer.wordpress.org/resource/dashicons/) icon slug string, or an SVG WP element, to be rendered when the sidebar is pinned to toolbar. * * @example ES5 * ```js @@ -129,7 +129,7 @@ function PluginSidebar( props ) { * ); * ``` * - * @return {import('@wordpress/element').WPComponent} Plugin sidebar component. + * @return {WPComponent} Plugin sidebar component. */ export default compose( withPluginContext( ( context, ownProps ) => { diff --git a/packages/edit-post/src/hooks/validate-multiple-use/index.js b/packages/edit-post/src/hooks/validate-multiple-use/index.js index 6dca911db6ed08..54a502603c2064 100644 --- a/packages/edit-post/src/hooks/validate-multiple-use/index.js +++ b/packages/edit-post/src/hooks/validate-multiple-use/index.js @@ -28,9 +28,9 @@ const enhance = compose( * "original" block is not the current one. Thus, an inexisting * `originalBlockClientId` prop signals that the block is valid. * - * @param {import('@wordpress/element').WPComponent} WrappedBlockEdit A filtered BlockEdit instance. + * @param {WPComponent} WrappedBlockEdit A filtered BlockEdit instance. * - * @return {import('@wordpress/element').WPComponent} Enhanced component with merged state data props. + * @return {WPComponent} Enhanced component with merged state data props. */ withSelect( ( select, block ) => { const multiple = hasBlockSupport( block.name, 'multiple', true ); diff --git a/packages/edit-widgets/src/components/widget-area/selection-observer.js b/packages/edit-widgets/src/components/widget-area/selection-observer.js index 6a46ca1d0527f3..3b1cdf5c378e49 100644 --- a/packages/edit-widgets/src/components/widget-area/selection-observer.js +++ b/packages/edit-widgets/src/components/widget-area/selection-observer.js @@ -10,7 +10,7 @@ import { withSelect, withDispatch } from '@wordpress/data'; * can be used to ensuring that only one block appears as selected * when multiple editors exist in a page. * - * @type {import('@wordpress/element').WPComponent} + * @type {WPComponent} */ class SelectionObserver extends Component { diff --git a/packages/editor/src/components/autocompleters/block.js b/packages/editor/src/components/autocompleters/block.js index 19a18d8c9032d7..5311d01ec2b749 100644 --- a/packages/editor/src/components/autocompleters/block.js +++ b/packages/editor/src/components/autocompleters/block.js @@ -27,7 +27,7 @@ function defaultGetBlockInsertionParentClientId() { * @param {string} rootClientId Client ID of the block for which to retrieve * inserter items. * - * @return {Array} The inserter items for the specified + * @return {Array} The inserter items for the specified * parent. */ function defaultGetInserterItems( rootClientId ) { @@ -68,7 +68,7 @@ const fetchReusableBlocks = once( () => { /** * Creates a blocks repeater for replacing the current block with a selected block type. * - * @return {import('@wordpress/components').Completer} A blocks completer. + * @return {WPCompleter} A blocks completer. */ export function createBlockCompleter( { // Allow store-based selectors to be overridden for unit test. @@ -119,6 +119,6 @@ export function createBlockCompleter( { /** * Creates a blocks repeater for replacing the current block with a selected block type. * - * @return {import('@wordpress/components').Completer} A blocks completer. + * @return {WPCompleter} A blocks completer. */ export default createBlockCompleter(); diff --git a/packages/editor/src/components/autocompleters/user.js b/packages/editor/src/components/autocompleters/user.js index 9f0b84f39ff59f..1dea163ee16443 100644 --- a/packages/editor/src/components/autocompleters/user.js +++ b/packages/editor/src/components/autocompleters/user.js @@ -6,7 +6,7 @@ import apiFetch from '@wordpress/api-fetch'; /** * A user mentions completer. * - * @type {import('@wordpress/components').Completer} + * @type {WPCompleter} */ export default { name: 'users', diff --git a/packages/editor/src/components/post-type-support-check/index.js b/packages/editor/src/components/post-type-support-check/index.js index 96d8e8e44b5b02..7aae5e6abb0362 100644 --- a/packages/editor/src/components/post-type-support-check/index.js +++ b/packages/editor/src/components/post-type-support-check/index.js @@ -12,14 +12,14 @@ import { withSelect } from '@wordpress/data'; * A component which renders its own children only if the current editor post * type supports one of the given `supportKeys` prop. * - * @param {Object} props Props. - * @param {string} [props.postType] Current post type. - * @param {import('@wordpress/element').WPElement} props.children Children to be rendered if post + * @param {Object} props Props. + * @param {string} [props.postType] Current post type. + * @param {WPElement} props.children Children to be rendered if post * type supports. * @param {(string|string[])} props.supportKeys String or string array of keys * to test. * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ export function PostTypeSupportCheck( { postType, children, supportKeys } ) { let isSupported = true; diff --git a/packages/editor/src/store/selectors.js b/packages/editor/src/store/selectors.js index f972ce4c9e3283..a8c216d4b2083f 100644 --- a/packages/editor/src/store/selectors.js +++ b/packages/editor/src/store/selectors.js @@ -827,7 +827,7 @@ export function getSuggestedPostFormat( state ) { * * @param {Object} state Editor state. * - * @return {import('@wordpress/blocks').WPBlockType[]} Filtered set of blocks for save. + * @return {WPBlock[]} Filtered set of blocks for save. */ export function getBlocksForSerialization( state ) { deprecated( '`core/editor` getBlocksForSerialization selector', { diff --git a/packages/element/README.md b/packages/element/README.md index 89424f857f0cdc..d592235c5dd8d9 100755 --- a/packages/element/README.md +++ b/packages/element/README.md @@ -148,8 +148,8 @@ _Related_ _Parameters_ -- _component_ `null`: Component -- _target_ `Element`: DOM node into which element should be rendered +- _child_ `WPElement`: Any renderable child, such as an element, string, or fragment. +- _container_ `HTMLElement`: DOM node into which element should be rendered. # **createRef** @@ -163,12 +163,11 @@ _Returns_ # **findDOMNode** -Finds the dom node of a React component +Finds the dom node of a React component. _Parameters_ -- _component_ `null`: component's instance -- _target_ `Element`: DOM node into which element should be rendered +- _component_ `WPComponent`: Component's instance. # **forwardRef** @@ -183,7 +182,7 @@ _Parameters_ _Returns_ -- `Component`: Enhanced component. +- `WPComponent`: Enhanced component. # **Fragment** @@ -240,7 +239,7 @@ _Parameters_ _Returns_ -- `null`: Dangerously-rendering component. +- `WPComponent`: Dangerously-rendering component. # **render** @@ -248,8 +247,8 @@ Renders a given element into the target DOM node. _Parameters_ -- _element_ `null`: Element to render. -- _target_ `Element`: DOM node into which element should be rendered. +- _element_ `WPElement`: Element to render. +- _target_ `HTMLElement`: DOM node into which element should be rendered. # **renderToString** @@ -257,7 +256,7 @@ Serializes a React element to string. _Parameters_ -- _element_ `null`: Element to serialize. +- _element_ `WPElement`: Element to serialize. - _context_ `?Object`: Context object. - _legacyContext_ `?Object`: Legacy context object. diff --git a/packages/element/src/raw-html.js b/packages/element/src/raw-html.js index ea3f47172de680..0f56060e3057b6 100644 --- a/packages/element/src/raw-html.js +++ b/packages/element/src/raw-html.js @@ -13,7 +13,7 @@ import { createElement } from './react'; * @param {string} props.children HTML to render. * @param {Object} props.props Any additonal props to be set on the containing div. * - * @return {import('@wordpress/element').WPComponent} Dangerously-rendering component. + * @return {WPComponent} Dangerously-rendering component. */ export default function RawHTML( { children, ...props } ) { // The DIV wrapper will be stripped by serializer, unless there are diff --git a/packages/element/src/react-platform.js b/packages/element/src/react-platform.js index 81dbf5fe35acde..44a3422ed79773 100644 --- a/packages/element/src/react-platform.js +++ b/packages/element/src/react-platform.js @@ -13,24 +13,24 @@ import { * * @see https://github.com/facebook/react/issues/10309#issuecomment-318433235 * - * @param {import('@wordpress/element').WPComponent} component Component - * @param {Element} target DOM node into which element should be rendered + * @param {WPElement} child Any renderable child, such as an element, + * string, or fragment. + * @param {HTMLElement} container DOM node into which element should be rendered. */ export { createPortal }; /** - * Finds the dom node of a React component + * Finds the dom node of a React component. * - * @param {import('@wordpress/element').WPComponent} component component's instance - * @param {Element} target DOM node into which element should be rendered + * @param {WPComponent} component Component's instance. */ export { findDOMNode }; /** * Renders a given element into the target DOM node. * - * @param {import('@wordpress/element').WPElement} element Element to render. - * @param {Element} target DOM node into which element should be rendered. + * @param {WPElement} element Element to render. + * @param {HTMLElement} target DOM node into which element should be rendered. */ export { render }; diff --git a/packages/element/src/react.js b/packages/element/src/react.js index 87e3b280106a77..2776f514b329e5 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 {import('react').ReactElement} WPElement + * @typedef {react.ReactElement} WPElement */ /** * Object containing a React component. * - * @typedef {import('react').Component} WPComponent + * @typedef {react.Component} WPComponent */ /** * Object containing a React synthetic event. * - * @typedef {import('react').SyntheticEvent} WPSyntheticEvent + * @typedef {react.SyntheticEvent} WPSyntheticEvent */ /** @@ -107,7 +107,7 @@ export { createRef }; * @param {Function} forwarder Function passed `props` and `ref`, expected to * return an element. * - * @return {Component} Enhanced component. + * @return {WPComponent} Enhanced component. */ export { forwardRef }; diff --git a/packages/element/src/serialize.js b/packages/element/src/serialize.js index 2e20032e0e85e1..b700831f1dccd0 100644 --- a/packages/element/src/serialize.js +++ b/packages/element/src/serialize.js @@ -348,9 +348,9 @@ function getNormalStylePropertyValue( property, value ) { /** * Serializes a React element to string. * - * @param {import('@wordpress/element').WPElement} element Element to serialize. - * @param {?Object} context Context object. - * @param {?Object} legacyContext Legacy context object. + * @param {WPElement} element Element to serialize. + * @param {?Object} context Context object. + * @param {?Object} legacyContext Legacy context object. * * @return {string} Serialized element. */ diff --git a/packages/eslint-plugin/configs/jsdoc.js b/packages/eslint-plugin/configs/jsdoc.js index 614816cb734a21..8e0935dc316881 100644 --- a/packages/eslint-plugin/configs/jsdoc.js +++ b/packages/eslint-plugin/configs/jsdoc.js @@ -1,5 +1,55 @@ +/** + * External dependencies + */ const globals = require( 'globals' ); +/** + * The temporary list of types defined in Gutenberg which are whitelisted to avoid + * ESLint warnings. It should be removed once importing is going to be implemented + * in the tool which generates public APIs from JSDoc comments. Related issue to + * fix the root cause `@wordpress/docgen`: + * https://github.com/WordPress/gutenberg/issues/18045. + */ +const temporaryWordPressInternalTypes = [ + 'WPBlockChildren', + 'WPBlockNode', + 'WPBlockSelection', + 'WPBlockSerializationOptions', + 'WPBlock', + 'WPBlockTypeIcon', + 'WPBlockTypeIconRender', + 'WPBlockTypeIconDescriptor', + 'WPDataPersistencePluginOptions', + 'WPDataPlugin', + 'WPDataRegistry', + 'WPComponent', + 'WPCompleter', + 'WPElement', + 'WPFormat', + 'WPEditorInserterItem', + 'WPNotice', + 'WPNoticeAction', + 'WPPlugin', + 'WPShortcode', + 'WPShortcodeAttrs', + 'WPShortcodeMatch', + 'WPSyntheticEvent', +]; + +/** + * The temporary list of external types used in Gutenberg which are whitelisted + * to avoid ESLint warnings. It's similar to `wordpressInternalTypes` and it + * should be removed once the related issues is fixed: + * https://github.com/WordPress/gutenberg/issues/18045 + */ +const temporaryExternalTypes = [ + 'DOMHighResTimeStamp', + 'espree', + 'moment', + 'puppeteer', + 'react', +]; + /** * Helpful utilities that are globally defined and known to the TypeScript compiler. * @@ -50,6 +100,8 @@ module.exports = { // generally refer to window-level event listeners and are not a valid type to reference (e.g. `onclick`). ...Object.keys( globals.browser ).filter( ( k ) => /^[A-Z]/.test( k ) ), ...typescriptUtilityTypes, + ...temporaryWordPressInternalTypes, + ...temporaryExternalTypes, 'void', ], } ], diff --git a/packages/jest-puppeteer-axe/src/index.js b/packages/jest-puppeteer-axe/src/index.js index d078ca8b21d66d..7bba05d8965d28 100644 --- a/packages/jest-puppeteer-axe/src/index.js +++ b/packages/jest-puppeteer-axe/src/index.js @@ -53,13 +53,13 @@ function formatViolations( violations ) { * * @see https://github.com/dequelabs/axe-puppeteer * - * @param {import('puppeteer').Page} page Puppeteer's page instance. - * @param {?Object} params Optional Axe API options. - * @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 {puppeteer.Page} page Puppeteer's page instance. + * @param {?Object} params Optional Axe API options. + * @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. * * @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 2d67195dcc7fc2..358a159aa8dc66 100644 --- a/packages/notices/src/store/selectors.js +++ b/packages/notices/src/store/selectors.js @@ -34,7 +34,7 @@ const DEFAULT_NOTICES = []; * @property {boolean} speak Whether the notice content should be * announced to screen readers. Defaults to * `true`. - * @property {import('./actions').WPNoticeAction[]} actions User actions to present with notice. + * @property {WPNoticeAction[]} actions User actions to present with notice. * */ diff --git a/packages/plugins/README.md b/packages/plugins/README.md index 1ad70184678136..9bf049e1bc6abc 100644 --- a/packages/plugins/README.md +++ b/packages/plugins/README.md @@ -71,7 +71,7 @@ const Layout = () => ( _Returns_ -- `null`: The component to be rendered. +- `WPComponent`: The component to be rendered. # **registerPlugin** @@ -189,7 +189,7 @@ _Parameters_ _Returns_ -- `null`: Enhanced component with injected context as props. +- `WPComponent`: Enhanced component with injected context as props. diff --git a/packages/plugins/src/api/index.js b/packages/plugins/src/api/index.js index 81ec513a0351f0..5e8fe1d19c851d 100644 --- a/packages/plugins/src/api/index.js +++ b/packages/plugins/src/api/index.js @@ -15,15 +15,15 @@ import { isFunction } from 'lodash'; * * @typedef {Object} WPPlugin * - * @property {string} name A string identifying the plugin. Must be - * unique across all registered plugins. - * unique across all registered plugins. - * @property {string|import('@wordpress/element').WPElement|Function} icon An icon to be shown in the UI. It can - * be a slug of the Dashicon, or an element - * (or function returning an element) if you - * choose to render your own SVG. - * @property {Function} render A component containing the UI elements - * to be rendered. + * @property {string} name A string identifying the plugin. Must be + * unique across all registered plugins. + * unique across all registered plugins. + * @property {string|WPElement|Function} icon An icon to be shown in the UI. It can + * be a slug of the Dashicon, or an element + * (or function returning an element) if you + * choose to render your own SVG. + * @property {Function} render A component containing the UI elements + * to be rendered. */ /** diff --git a/packages/plugins/src/components/plugin-area/index.js b/packages/plugins/src/components/plugin-area/index.js index 01eda548d695c2..e03e5458d50ef4 100644 --- a/packages/plugins/src/components/plugin-area/index.js +++ b/packages/plugins/src/components/plugin-area/index.js @@ -47,7 +47,7 @@ import { getPlugins } from '../../api'; * ); * ``` * - * @return {import('@wordpress/element').WPComponent} The component to be rendered. + * @return {WPComponent} The component to be rendered. */ class PluginArea extends Component { constructor() { diff --git a/packages/plugins/src/components/plugin-context/index.js b/packages/plugins/src/components/plugin-context/index.js index 0ac95bd43bb62a..586891c67eb4ee 100644 --- a/packages/plugins/src/components/plugin-context/index.js +++ b/packages/plugins/src/components/plugin-context/index.js @@ -19,7 +19,7 @@ export { Provider as PluginContextProvider }; * expected to return object of props to * merge with the component's own props. * - * @return {import('@wordpress/element').WPComponent} Enhanced component with injected context as props. + * @return {WPComponent} Enhanced component with injected context as props. */ export const withPluginContext = ( mapContextToProps ) => createHigherOrderComponent( ( OriginalComponent ) => { return ( props ) => ( diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md index fec5018aac0ac5..e911c714792064 100644 --- a/packages/rich-text/README.md +++ b/packages/rich-text/README.md @@ -343,7 +343,7 @@ _Parameters_ _Returns_ -- `null`: The previous format value, if it has been successfully unregistered; otherwise `undefined`. +- `(WPFormat|undefined)`: The previous format value, if it has been successfully unregistered; otherwise `undefined`. diff --git a/packages/rich-text/src/component/index.js b/packages/rich-text/src/component/index.js index 871f3450e30b1c..e028ba0611623b 100644 --- a/packages/rich-text/src/component/index.js +++ b/packages/rich-text/src/component/index.js @@ -337,7 +337,7 @@ class RichText extends Component { /** * Handle input on the next selection change event. * - * @param {import('@wordpress/element').WPSyntheticEvent} event Synthetic input event. + * @param {WPSyntheticEvent} event Synthetic input event. */ onInput( event ) { // For Input Method Editor (IME), used in Chinese, Japanese, and Korean @@ -437,7 +437,7 @@ class RichText extends Component { * native events, `keyup`, `mouseup` and `touchend` synthetic events, and * animation frames after the `focus` event. * - * @param {Event|import('@wordpress/element').WPSyntheticEvent|DOMHighResTimeStamp} event + * @param {Event|WPSyntheticEvent|DOMHighResTimeStamp} event */ onSelectionChange( event ) { if ( @@ -579,7 +579,7 @@ class RichText extends Component { * - delete content if everything is selected, * - trigger the onDelete prop when selection is uncollapsed and at an edge. * - * @param {import('@wordpress/element').WPSyntheticEvent} event A synthetic keyboard event. + * @param {WPSyntheticEvent} event A synthetic keyboard event. */ handleDelete( event ) { const { keyCode } = event; @@ -637,7 +637,7 @@ class RichText extends Component { /** * Triggers the `onEnter` prop on keydown. * - * @param {import('@wordpress/element').WPSyntheticEvent} event A synthetic keyboard event. + * @param {WPSyntheticEvent} event A synthetic keyboard event. */ handleEnter( event ) { if ( event.keyCode !== ENTER ) { @@ -662,7 +662,7 @@ class RichText extends Component { /** * Indents list items on space keydown. * - * @param {import('@wordpress/element').WPSyntheticEvent} event A synthetic keyboard event. + * @param {WPSyntheticEvent} event A synthetic keyboard event. */ handleSpace( event ) { const { keyCode, shiftKey, altKey, metaKey, ctrlKey } = event; @@ -699,7 +699,7 @@ class RichText extends Component { * navigation is handled separately to move correctly around format * boundaries. * - * @param {import('@wordpress/element').WPSyntheticEvent} event A synthetic keyboard event. + * @param {WPSyntheticEvent} event A synthetic keyboard event. */ handleHorizontalNavigation( event ) { const { keyCode, shiftKey, altKey, metaKey, ctrlKey } = event; @@ -805,7 +805,7 @@ class RichText extends Component { * Select object when they are clicked. The browser will not set any * selection when clicking e.g. an image. * - * @param {import('@wordpress/element').WPSyntheticEvent} event Synthetic mousedown or touchstart event. + * @param {WPSyntheticEvent} event Synthetic mousedown or touchstart event. */ onPointerDown( event ) { const { target } = event; diff --git a/packages/rich-text/src/unregister-format-type.js b/packages/rich-text/src/unregister-format-type.js index 2c4b36f8883e02..a70c1d1d417f2b 100644 --- a/packages/rich-text/src/unregister-format-type.js +++ b/packages/rich-text/src/unregister-format-type.js @@ -9,8 +9,8 @@ import { removeFilter } from '@wordpress/hooks'; * * @param {string} name Format name. * - * @return {import('./register-format-type').WPFormat|undefined} The previous format value, - * if it has been successfully unregistered; otherwise `undefined`. + * @return {WPFormat|undefined} The previous format value, if it has been successfully + * unregistered; otherwise `undefined`. */ export function unregisterFormatType( name ) { const oldFormat = select( 'core/rich-text' ).getFormatType( name );