From 1da5770513c08449305fd19d74d5e054f082c952 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 18 Oct 2019 19:18:32 +0200 Subject: [PATCH] Code style: Fix ESLint warnings reported for JSDoc definitions --- .../developers/data/data-core-block-editor.md | 2 +- .../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 | 2 +- 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 | 28 ++++++++------ 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 +- .../post-type-support-check/index.js | 14 +++---- packages/editor/src/store/actions.native.js | 4 +- 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 | 27 +++++++++---- .../src/components/plugin-area/index.js | 2 +- .../src/components/plugin-context/index.js | 2 +- packages/rich-text/src/component/index.js | 14 +++---- 94 files changed, 335 insertions(+), 300 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 eb9201165dafd..c087b1191cd5e 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** 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 93efda1bd0bc4..49801a69817be 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 8b20edac6d37c..29c1fc810e993 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 e937601ec864b..92dcf6be1d0ac 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 ce0cda7d3542a..79f3f41991c08 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 d9c7818065c0b..aa2bf9680208e 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 863cdc3e5d6fa..74f7f4c6ad453 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 81f05b40bf708..56bc7e840d47e 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 8a6692a422a6f..9e8fb4982d72b 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 b6f33b1b8590f..69d04f2f62518 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 2592ba3abd052..df1a49da06990 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 5abb1ae4ef923..12eae37767fb2 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 4c06402af3821..0170d16577f91 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 1cb3e51109727..222aec5a30118 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 488dd6244d8c6..519e36d641058 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 8e2f2e677397b..eccb227e51965 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 165566a5bbbd1..ee275d3edcccb 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 7600b2cd8747c..d636d13e025ba 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 9b78c39bbfeb0..15a9d060769bd 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 bac77a37ea42a..17792d692f894 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 7f03542fd841d..feeee81942991 100644 --- a/packages/block-editor/src/store/selectors.js +++ b/packages/block-editor/src/store/selectors.js @@ -255,7 +255,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( diff --git a/packages/block-library/src/columns/utils.js b/packages/block-library/src/columns/utils.js index a6773d469c98f..33c77d2dace16 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 1af3f49adef88..95832b946e97e 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 7cf70d2da7815..eff87d18466ba 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 6300eac329f15..0b357e7f1272a 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 024f9e9d55a3e..b95f7bc8f3a66 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 98b3928962a44..a392fafd32d42 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 99dc98b5c3204..5d66227aa2d23 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 352550a87be80..e9343ad08d63a 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 283ccd92633b0..34c0ed239df87 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 7361494a61e68..eee7f5331f075 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('@wordpress/date').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 2b504878bdf52..f193b348b9901 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 49a44608039ce..aa5710baad762 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 de17dc62aeb57..389e4c2cffcfa 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 b7cc7c8ca7a0b..76ffa2e5ad189 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 286171a06e0ca..95cd509eb3ed2 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 f4a64c289b4e7..dd8b0bef8f19e 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 2a12363e7fde0..9e5bf053417d0 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 0d600aac62f14..07e62cb18a522 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 ca41d32bb6e1b..8a795f98e2b5b 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 dc47f26e99565..9c69fed546567 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 e721fbb796479..d9551f5582e2a 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 53c09ec56f888..cb8cbfb42ecf4 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 910dd94fddc19..5a0b1cfec3a57 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 19e639043bd28..7f59410853ac6 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 448193468c94e..4bac128095b93 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 892a6e572a99b..a2bb3ccbe6dee 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 dc77d54994ac0..a79aaba7e33d8 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 a76019371e725..e3f3d9d50e50e 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 2247a253a189d..9f613c7b9d0f5 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 32d1c8e1a40fd..b27c1d278ad24 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 f9659e7e865a8..feee44ea313c9 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 2a10c7a8e7afc..e6e867fecdcb8 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 b3bd639fcddfa..3953a75392859 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 871a7e5613359..e5461a4204d72 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 e7e0a2ae7c620..0783f264c9142 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 c4bad6ef1636e..e45bb664c8551 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_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js. _Returns_ @@ -36,7 +36,7 @@ Formats a date (like `date_i18n()` in PHP). _Parameters_ - _dateFormat_ `string`: PHP-style formatting string. See php.net/date. -- _dateValue_ `(Date|string|moment|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js. - _gmt_ `boolean`: True for GMT/UTC, false for site's timezone. _Returns_ @@ -50,7 +50,7 @@ Formats a date. Does not alter the date's timezone. _Parameters_ - _dateFormat_ `string`: PHP-style formatting string. See php.net/date. -- _dateValue_ `(Date|string|moment|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js. _Returns_ @@ -75,7 +75,7 @@ Formats a date (like `date()` in PHP), in the UTC timezone. _Parameters_ - _dateFormat_ `string`: PHP-style formatting string. See php.net/date. -- _dateValue_ `(Date|string|moment|null)`: Date object or string, parsable by moment.js. +- _dateValue_ `(Date|string|Moment|null)`: Date object or string, parsable by moment.js. _Returns_ diff --git a/packages/date/src/index.js b/packages/date/src/index.js index 39b4425ea2da2..315c059e97c06 100644 --- a/packages/date/src/index.js +++ b/packages/date/src/index.js @@ -5,6 +5,12 @@ import momentLib from 'moment'; import 'moment-timezone/moment-timezone'; import 'moment-timezone/moment-timezone-utils'; +/** + * Object containing `moment` instance. + * + * @typedef {Object} Moment + */ + const WP_ZONE = 'WP'; // Changes made here will likely need to be made in `lib/client-assets.php` as @@ -145,7 +151,7 @@ const formatMap = { /** * Gets the ordinal suffix. * - * @param {moment} momentDate Moment instance. + * @param {Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -160,7 +166,7 @@ const formatMap = { /** * Gets the day of the year (zero-indexed). * - * @param {moment} momentDate Moment instance. + * @param {Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -180,7 +186,7 @@ const formatMap = { /** * Gets the days in the month. * - * @param {moment} momentDate Moment instance. + * @param {Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -192,7 +198,7 @@ const formatMap = { /** * Gets whether the current year is a leap year. * - * @param {moment} momentDate Moment instance. + * @param {Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -209,7 +215,7 @@ const formatMap = { /** * Gets the current time in Swatch Internet Time (.beats). * - * @param {moment} momentDate Moment instance. + * @param {Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -240,7 +246,7 @@ const formatMap = { /** * Gets whether the timezone is in DST currently. * - * @param {moment} momentDate Moment instance. + * @param {Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -253,7 +259,7 @@ const formatMap = { /** * Gets the timezone offset in seconds. * - * @param {moment} momentDate Moment instance. + * @param {Moment} momentDate Moment instance. * * @return {string} Formatted date. */ @@ -275,7 +281,7 @@ const formatMap = { * * @param {string} dateFormat PHP-style formatting string. * See php.net/date. - * @param {(Date|string|moment|null)} dateValue Date object or string, + * @param {(Date|string|Moment|null)} dateValue Date object or string, * parsable by moment.js. * * @return {string} Formatted date. @@ -316,7 +322,7 @@ export function format( dateFormat, dateValue = new Date() ) { * * @param {string} dateFormat PHP-style formatting string. * See php.net/date. - * @param {(Date|string|moment|null)} dateValue Date object or string, + * @param {(Date|string|Moment|null)} dateValue Date object or string, * parsable by moment.js. * * @return {string} Formatted date. @@ -332,7 +338,7 @@ export function date( dateFormat, dateValue = new Date() ) { * * @param {string} dateFormat PHP-style formatting string. * See php.net/date. - * @param {(Date|string|moment|null)} dateValue Date object or string, + * @param {(Date|string|Moment|null)} dateValue Date object or string, * parsable by moment.js. * * @return {string} Formatted date. @@ -347,7 +353,7 @@ export function gmdate( dateFormat, dateValue = new Date() ) { * * @param {string} dateFormat PHP-style formatting string. * See php.net/date. - * @param {(Date|string|moment|null)} dateValue Date object or string, + * @param {(Date|string|Moment|null)} dateValue Date object or string, * parsable by moment.js. * @param {boolean} gmt True for GMT/UTC, false for * site's timezone. diff --git a/packages/e2e-test-utils/README.md b/packages/e2e-test-utils/README.md index d8b3263c2e6e9..a90533b68ae70 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 f8f2976de67a7..598995828661c 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 a4167fe6e2e6c..f4a5f2f8a9874 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 ff60dca5f0078..4bd283be731db 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 9b505cf3b1280..924a5c939b3da 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 56e5976513746..877d1c0dd04ae 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 505f8cca3ba3a..d460b7a0cd8f1 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 3b7b01a53e6dd..b6c2e914f8b75 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 8503692c289b0..881034393fd38 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 e29ec22e90a20..9597af6c328e5 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 e1849f2e7890e..ea0167b4ce230 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 ef10b4ed77ef3..bdc118376efa0 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 a84124905d7d4..e050d1f0df850 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 e099fa232e84f..cbedd5f7c88c8 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 4a3b02fba2803..54d6f1c944b44 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 5303de703b30b..e59e6eb96d057 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 ea2958949f7e2..6dca911db6ed0 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 2430ee4108723..fff04ac721fe3 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 3b1cdf5c378e4..6a46ca1d0527f 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/post-type-support-check/index.js b/packages/editor/src/components/post-type-support-check/index.js index 8096e4ccf7f8d..96d8e8e44b5b0 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 17733a0e47b40..0154c92324640 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/selectors.js b/packages/editor/src/store/selectors.js index a8c216d4b2083..f972ce4c9e328 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 0b96812eacb53..89424f857f0cd 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 2fa3618c417d8..ea3f47172de68 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 e4ca37da7e11b..81dbf5fe35acd 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 722085de1fc77..87e3b280106a7 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 b700831f1dccd..2e20032e0e85e 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 336cec9bcf816..d078ca8b21d66 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 f1771b6ca8ae2..0fed89a60e0f3 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 3a0bc75ad0f02..2d67195dcc7fc 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 9225bd97077ee..58decf8945519 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 2875c76b0fa8d..1ad7018467813 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 6e6ea102a80ff..1ac6b9f642ff4 100644 --- a/packages/plugins/src/api/index.js +++ b/packages/plugins/src/api/index.js @@ -10,21 +10,32 @@ import { applyFilters, doAction } from '@wordpress/hooks'; */ import { isFunction } from 'lodash'; +/** + * Defined behavior of a plugin type. + * + * @typedef {Object} WPPlugin + */ + /** * Plugin definitions keyed by plugin name. * * @type {Object.} + * + * @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. */ 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 +101,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 +192,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 +201,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 1cf6f15b52879..01eda548d695c 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 75fb1b8f1dea0..0ac95bd43bb62 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/src/component/index.js b/packages/rich-text/src/component/index.js index c82feae869d1e..7446e16ca43fd 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 {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;