@wordpress/plugins 5.8.0 → 6.1.0

package/build-types/api/index.d.ts

@@ -0,0 +1,149 @@
+import type { IconType } from '@wordpress/components';
+import type { WPComponent } from '@wordpress/element';
+/**
+ * Defined behavior of a plugin type.
+ */
+export interface WPPlugin {
+    /**
+     * A string identifying the plugin. Must be unique across all registered plugins.
+     */
+    name: string;
+    /**
+     * 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.
+     */
+    icon?: IconType;
+    /**
+     * A component containing the UI elements to be rendered.
+     */
+    render: WPComponent;
+    /**
+     * The optional scope to be used when rendering inside a plugin area.
+     * No scope by default.
+     */
+    scope?: string;
+}
+type PluginSettings = Omit<WPPlugin, 'name'>;
+/**
+ * Registers a plugin to the editor.
+ *
+ * @param name     A string identifying the plugin. Must be
+ *                 unique across all registered plugins.
+ * @param settings The settings for this plugin.
+ *
+ * @example
+ * ```js
+ * // Using ES5 syntax
+ * var el = wp.element.createElement;
+ * var Fragment = wp.element.Fragment;
+ * var PluginSidebar = wp.editPost.PluginSidebar;
+ * var PluginSidebarMoreMenuItem = wp.editPost.PluginSidebarMoreMenuItem;
+ * var registerPlugin = wp.plugins.registerPlugin;
+ * var moreIcon = wp.element.createElement( 'svg' ); //... svg element.
+ *
+ * function Component() {
+ * 	return el(
+ * 		Fragment,
+ * 		{},
+ * 		el(
+ * 			PluginSidebarMoreMenuItem,
+ * 			{
+ * 				target: 'sidebar-name',
+ * 			},
+ * 			'My Sidebar'
+ * 		),
+ * 		el(
+ * 			PluginSidebar,
+ * 			{
+ * 				name: 'sidebar-name',
+ * 				title: 'My Sidebar',
+ * 			},
+ * 			'Content of the sidebar'
+ * 		)
+ * 	);
+ * }
+ * registerPlugin( 'plugin-name', {
+ * 	icon: moreIcon,
+ * 	render: Component,
+ * 	scope: 'my-page',
+ * } );
+ * ```
+ *
+ * @example
+ * ```js
+ * // Using ESNext syntax
+ * import { PluginSidebar, PluginSidebarMoreMenuItem } from '@wordpress/edit-post';
+ * import { registerPlugin } from '@wordpress/plugins';
+ * import { more } from '@wordpress/icons';
+ *
+ * const Component = () => (
+ * 	<>
+ * 		<PluginSidebarMoreMenuItem
+ * 			target="sidebar-name"
+ * 		>
+ * 			My Sidebar
+ * 		</PluginSidebarMoreMenuItem>
+ * 		<PluginSidebar
+ * 			name="sidebar-name"
+ * 			title="My Sidebar"
+ * 		>
+ * 			Content of the sidebar
+ * 		</PluginSidebar>
+ * 	</>
+ * );
+ *
+ * registerPlugin( 'plugin-name', {
+ * 	icon: more,
+ * 	render: Component,
+ * 	scope: 'my-page',
+ * } );
+ * ```
+ *
+ * @return The final plugin settings object.
+ */
+export declare function registerPlugin(name: string, settings: PluginSettings): PluginSettings | null;
+/**
+ * Unregisters a plugin by name.
+ *
+ * @param name Plugin name.
+ *
+ * @example
+ * ```js
+ * // Using ES5 syntax
+ * var unregisterPlugin = wp.plugins.unregisterPlugin;
+ *
+ * unregisterPlugin( 'plugin-name' );
+ * ```
+ *
+ * @example
+ * ```js
+ * // Using ESNext syntax
+ * import { unregisterPlugin } from '@wordpress/plugins';
+ *
+ * unregisterPlugin( 'plugin-name' );
+ * ```
+ *
+ * @return The previous plugin settings object, if it has been
+ *         successfully unregistered; otherwise `undefined`.
+ */
+export declare function unregisterPlugin(name: string): WPPlugin | undefined;
+/**
+ * Returns a registered plugin settings.
+ *
+ * @param name Plugin name.
+ *
+ * @return Plugin setting.
+ */
+export declare function getPlugin(name: string): WPPlugin | undefined;
+/**
+ * Returns all registered plugins without a scope or for a given scope.
+ *
+ * @param scope The scope to be used when rendering inside
+ *              a plugin area. No scope by default.
+ *
+ * @return The list of plugins without a scope or for a given scope.
+ */
+export declare function getPlugins(scope?: string): WPPlugin[];
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build-types/api/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB;;OAEG;IACH,MAAM,EAAE,WAAW,CAAC;IAEpB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED,KAAK,cAAc,GAAG,IAAI,CAAE,QAAQ,EAAE,MAAM,CAAE,CAAC;AAO/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,wBAAgB,cAAc,CAC7B,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,cAAc,GACtB,cAAc,GAAG,IAAI,CAyDvB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAE,IAAI,EAAE,MAAM,GAAI,QAAQ,GAAG,SAAS,CAWrE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAE,IAAI,EAAE,MAAM,GAAI,QAAQ,GAAG,SAAS,CAE9D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAE,KAAK,CAAC,EAAE,MAAM,GAAI,QAAQ,EAAE,CAIvD"}

package/build-types/components/index.d.ts

@@ -0,0 +1,3 @@
+export { default as PluginArea } from "./plugin-area";
+export { withPluginContext } from "./plugin-context";
+//# sourceMappingURL=index.d.ts.map

package/build-types/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.js"],"names":[],"mappings":""}

package/build-types/components/plugin-area/index.d.ts

@@ -0,0 +1,44 @@
+import type { WPPlugin } from '../../api';
+/**
+ * A component that renders all plugin fills in a hidden div.
+ *
+ * @param  props
+ * @param  props.scope
+ * @param  props.onError
+ * @example
+ * ```js
+ * // Using ES5 syntax
+ * var el = wp.element.createElement;
+ * var PluginArea = wp.plugins.PluginArea;
+ *
+ * function Layout() {
+ * 	return el(
+ * 		'div',
+ * 		{ scope: 'my-page' },
+ * 		'Content of the page',
+ * 		PluginArea
+ * 	);
+ * }
+ * ```
+ *
+ * @example
+ * ```js
+ * // Using ESNext syntax
+ * import { PluginArea } from '@wordpress/plugins';
+ *
+ * const Layout = () => (
+ * 	<div>
+ * 		Content of the page
+ * 		<PluginArea scope="my-page" />
+ * 	</div>
+ * );
+ * ```
+ *
+ * @return {WPComponent} The component to be rendered.
+ */
+declare function PluginArea({ scope, onError, }: {
+    scope?: string;
+    onError?: (name: WPPlugin['name'], error: Error) => void;
+}): JSX.Element;
+export default PluginArea;
+//# sourceMappingURL=index.d.ts.map

package/build-types/components/plugin-area/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/plugin-area/index.tsx"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAS1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,iBAAS,UAAU,CAAE,EACpB,KAAK,EACL,OAAO,GACP,EAAE;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,CAAE,IAAI,EAAE,QAAQ,CAAE,MAAM,CAAE,EAAE,KAAK,EAAE,KAAK,KAAM,IAAI,CAAC;CAC7D,eA4DA;AAED,eAAe,UAAU,CAAC"}

package/build-types/components/plugin-context/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Internal dependencies
+ */
+import type { WPPlugin } from '../../api';
+export interface PluginContext {
+    name: null | WPPlugin['name'];
+    icon: null | WPPlugin['icon'];
+}
+declare const Provider: import("react").Provider<PluginContext>;
+export { Provider as PluginContextProvider };
+/**
+ * A Higher Order Component used to inject Plugin context to the
+ * wrapped component.
+ *
+ * @param  mapContextToProps Function called on every context change,
+ *                           expected to return object of props to
+ *                           merge with the component's own props.
+ *
+ * @return {WPComponent} Enhanced component with injected context as props.
+ */
+export declare const withPluginContext: (mapContextToProps: <T>(context: PluginContext, props: T) => T & PluginContext) => (Inner: import("react").ComponentType<any>) => (props: any) => JSX.Element;
+//# sourceMappingURL=index.d.ts.map

package/build-types/components/plugin-context/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/plugin-context/index.tsx"],"names":[],"mappings":"AAMA;;GAEG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,WAAW,aAAa;IAC7B,IAAI,EAAE,IAAI,GAAG,QAAQ,CAAE,MAAM,CAAE,CAAC;IAChC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAAE,MAAM,CAAE,CAAC;CAChC;AAED,QAAA,MAAkB,QAAQ,yCAGvB,CAAC;AAEJ,OAAO,EAAE,QAAQ,IAAI,qBAAqB,EAAE,CAAC;AAE7C;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,mCAEnB,aAAa,+GAeC,CAAC"}

package/build-types/components/plugin-error-boundary/index.d.ts

@@ -0,0 +1,19 @@
+export class PluginErrorBoundary extends Component<any, any, any> {
+    static getDerivedStateFromError(): {
+        hasError: boolean;
+    };
+    /**
+     * @param {Object} props
+     */
+    constructor(props: Object);
+    state: {
+        hasError: boolean;
+    };
+    /**
+     * @param {Error} error Error object passed by React.
+     */
+    componentDidCatch(error: Error): void;
+    render(): any;
+}
+import { Component } from "@wordpress/element/build-types/react";
+//# sourceMappingURL=index.d.ts.map

package/build-types/components/plugin-error-boundary/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/plugin-error-boundary/index.js"],"names":[],"mappings":"AAKA;IAWC;;MAEC;IAZD;;OAEG;IACH,mBAFW,MAAM,EAOhB;IAHA;;MAEC;IAOF;;OAEG;IACH,yBAFW,KAAK,QAOf;IAED,cAMC;CACD"}

package/build-types/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./components";
+export * from "./api";
+//# sourceMappingURL=index.d.ts.map

package/build-types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.js"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/plugins",
-	"version": "5.8.0",
+	"version": "6.1.0",
 	"description": "Plugins module for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -24,13 +24,15 @@
 	"main": "build/index.js",
 	"module": "build-module/index.js",
 	"react-native": "src/index",
+	"types": "build-types",
 	"dependencies": {
 		"@babel/runtime": "^7.16.0",
-		"@wordpress/compose": "^6.8.0",
-		"@wordpress/element": "^5.8.0",
-		"@wordpress/hooks": "^3.31.0",
-		"@wordpress/icons": "^9.22.0",
-		"@wordpress/is-shallow-equal": "^4.31.0",
+		"@wordpress/components": "^24.0.0",
+		"@wordpress/compose": "^6.10.0",
+		"@wordpress/element": "^5.10.0",
+		"@wordpress/hooks": "^3.33.0",
+		"@wordpress/icons": "^9.24.0",
+		"@wordpress/is-shallow-equal": "^4.33.0",
 		"memize": "^1.1.0"
 	},
 	"peerDependencies": {
@@ -39,5 +41,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "d61700b9f1c72ba0b030fc815ef1685b4f4031ec"
+	"gitHead": "e936127e1e13881f1a940b7bd1593a9e500147f3"
 }

package/src/api/{index.js → index.ts}

@@ -5,37 +5,50 @@
  */
 import { applyFilters, doAction } from '@wordpress/hooks';
 import { plugins as pluginsIcon } from '@wordpress/icons';
+import type { IconType } from '@wordpress/components';
+import type { WPComponent } from '@wordpress/element';
 
 /**
  * Defined behavior of a plugin type.
- *
- * @typedef {Object} WPPlugin
- *
- * @property {string}                    name    A string identifying the plugin. Must be
- *                                               unique across all registered plugins.
- * @property {string|WPElement|Function} [icon]  An icon to be shown in the UI. It can
- *                                               be a slug of the Dashicon, or an element
- *                                               (or function returning an element) if you
- *                                               choose to render your own SVG.
- * @property {Function}                  render  A component containing the UI elements
- *                                               to be rendered.
- * @property {string}                    [scope] The optional scope to be used when rendering inside
- *                                               a plugin area. No scope by default.
  */
+export interface WPPlugin {
+	/**
+	 * A string identifying the plugin. Must be unique across all registered plugins.
+	 */
+	name: string;
+
+	/**
+	 * 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.
+	 */
+	icon?: IconType;
+
+	/**
+	 * A component containing the UI elements to be rendered.
+	 */
+	render: WPComponent;
+
+	/**
+	 * The optional scope to be used when rendering inside a plugin area.
+	 * No scope by default.
+	 */
+	scope?: string;
+}
+
+type PluginSettings = Omit< WPPlugin, 'name' >;
 
 /**
  * Plugin definitions keyed by plugin name.
- *
- * @type {Object.<string,WPPlugin>}
  */
-const plugins = {};
+const plugins = {} as Record< string, WPPlugin >;
 
 /**
  * Registers a plugin to the editor.
  *
- * @param {string}                 name     A string identifying the plugin.Must be
- *                                          unique across all registered plugins.
- * @param {Omit<WPPlugin, 'name'>} settings The settings for this plugin.
+ * @param name     A string identifying the plugin. Must be
+ *                 unique across all registered plugins.
+ * @param settings The settings for this plugin.
  *
  * @example
  * ```js
@@ -105,9 +118,12 @@ const plugins = {};
  * } );
  * ```
  *
- * @return {WPPlugin} The final plugin settings object.
+ * @return The final plugin settings object.
  */
-export function registerPlugin( name, settings ) {
+export function registerPlugin(
+	name: string,
+	settings: PluginSettings
+): PluginSettings | null {
 	if ( typeof settings !== 'object' ) {
 		console.error( 'No settings object provided!' );
 		return null;
@@ -126,7 +142,11 @@ export function registerPlugin( name, settings ) {
 		console.error( `Plugin "${ name }" is already registered.` );
 	}
 
-	settings = applyFilters( 'plugins.registerPlugin', settings, name );
+	settings = applyFilters(
+		'plugins.registerPlugin',
+		settings,
+		name
+	) as PluginSettings;
 
 	const { render, scope } = settings;
 
@@ -165,7 +185,7 @@ export function registerPlugin( name, settings ) {
 /**
  * Unregisters a plugin by name.
  *
- * @param {string} name Plugin name.
+ * @param name Plugin name.
  *
  * @example
  * ```js
@@ -183,10 +203,10 @@ export function registerPlugin( name, settings ) {
  * unregisterPlugin( 'plugin-name' );
  * ```
  *
- * @return {WPPlugin | undefined} The previous plugin settings object, if it has been
- *                     successfully unregistered; otherwise `undefined`.
+ * @return The previous plugin settings object, if it has been
+ *         successfully unregistered; otherwise `undefined`.
  */
-export function unregisterPlugin( name ) {
+export function unregisterPlugin( name: string ): WPPlugin | undefined {
 	if ( ! plugins[ name ] ) {
 		console.error( 'Plugin "' + name + '" is not registered.' );
 		return;
@@ -202,23 +222,23 @@ export function unregisterPlugin( name ) {
 /**
  * Returns a registered plugin settings.
  *
- * @param {string} name Plugin name.
+ * @param name Plugin name.
  *
- * @return {?WPPlugin} Plugin setting.
+ * @return Plugin setting.
  */
-export function getPlugin( name ) {
+export function getPlugin( name: string ): WPPlugin | undefined {
 	return plugins[ name ];
 }
 
 /**
  * Returns all registered plugins without a scope or for a given scope.
  *
- * @param {string} [scope] The scope to be used when rendering inside
- *                         a plugin area. No scope by default.
+ * @param scope The scope to be used when rendering inside
+ *              a plugin area. No scope by default.
  *
- * @return {WPPlugin[]} The list of plugins without a scope or for a given scope.
+ * @return The list of plugins without a scope or for a given scope.
  */
-export function getPlugins( scope ) {
+export function getPlugins( scope?: string ): WPPlugin[] {
 	return Object.values( plugins ).filter(
 		( plugin ) => plugin.scope === scope
 	);

package/src/components/plugin-area/{index.js → index.tsx}

@@ -16,15 +16,22 @@ import isShallowEqual from '@wordpress/is-shallow-equal';
 import { PluginContextProvider } from '../plugin-context';
 import { PluginErrorBoundary } from '../plugin-error-boundary';
 import { getPlugins } from '../../api';
+import type { PluginContext } from '../plugin-context';
+import type { WPPlugin } from '../../api';
 
-const getPluginContext = memoize( ( icon, name ) => ( { icon, name } ) );
+const getPluginContext = memoize(
+	( icon: PluginContext[ 'icon' ], name: PluginContext[ 'name' ] ) => ( {
+		icon,
+		name,
+	} )
+);
 
 /**
  * A component that renders all plugin fills in a hidden div.
  *
- * @param {Object}             props
- * @param {string|undefined}   props.scope
- * @param {Function|undefined} props.onError
+ * @param  props
+ * @param  props.scope
+ * @param  props.onError
  * @example
  * ```js
  * // Using ES5 syntax
@@ -56,12 +63,23 @@ const getPluginContext = memoize( ( icon, name ) => ( { icon, name } ) );
  *
  * @return {WPComponent} The component to be rendered.
  */
-function PluginArea( { scope, onError } ) {
+function PluginArea( {
+	scope,
+	onError,
+}: {
+	scope?: string;
+	onError?: ( name: WPPlugin[ 'name' ], error: Error ) => void;
+} ) {
 	const store = useMemo( () => {
-		let lastValue;
+		let lastValue: WPPlugin[] = [];
 
 		return {
-			subscribe( listener ) {
+			subscribe(
+				listener: (
+					plugin: Omit< WPPlugin, 'name' >,
+					name: WPPlugin[ 'name' ]
+				) => void
+			) {
 				addAction(
 					'plugins.pluginRegistered',
 					'core/plugins/plugin-area/plugins-registered',

package/src/components/plugin-context/{index.js → index.tsx}

@@ -4,7 +4,17 @@
 import { createContext } from '@wordpress/element';
 import { createHigherOrderComponent } from '@wordpress/compose';
 
-const { Consumer, Provider } = createContext( {
+/**
+ * Internal dependencies
+ */
+import type { WPPlugin } from '../../api';
+
+export interface PluginContext {
+	name: null | WPPlugin[ 'name' ];
+	icon: null | WPPlugin[ 'icon' ];
+}
+
+const { Consumer, Provider } = createContext< PluginContext >( {
 	name: null,
 	icon: null,
 } );
@@ -15,13 +25,18 @@ export { Provider as PluginContextProvider };
  * A Higher Order Component used to inject Plugin context to the
  * wrapped component.
  *
- * @param {Function} mapContextToProps Function called on every context change,
- *                                     expected to return object of props to
- *                                     merge with the component's own props.
+ * @param  mapContextToProps Function called on every context change,
+ *                           expected to return object of props to
+ *                           merge with the component's own props.
  *
  * @return {WPComponent} Enhanced component with injected context as props.
  */
-export const withPluginContext = ( mapContextToProps ) =>
+export const withPluginContext = (
+	mapContextToProps: < T >(
+		context: PluginContext,
+		props: T
+	) => T & PluginContext
+) =>
 	createHigherOrderComponent( ( OriginalComponent ) => {
 		return ( props ) => (
 			<Consumer>

package/src/components/plugin-error-boundary/index.js

@@ -4,6 +4,9 @@
 import { Component } from '@wordpress/element';
 
 export class PluginErrorBoundary extends Component {
+	/**
+	 * @param {Object} props
+	 */
 	constructor( props ) {
 		super( props );
 		this.state = {
@@ -15,6 +18,9 @@ export class PluginErrorBoundary extends Component {
 		return { hasError: true };
 	}
 
+	/**
+	 * @param {Error} error Error object passed by React.
+	 */
 	componentDidCatch( error ) {
 		const { name, onError } = this.props;
 		if ( onError ) {

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"rootDir": "src",
+		"declarationDir": "build-types",
+		"types": [ "gutenberg-env" ],
+		"skipLibCheck": true
+	},
+	"references": [
+		{ "path": "../components" },
+		{ "path": "../compose" },
+		{ "path": "../element" },
+		{ "path": "../hooks" },
+		{ "path": "../icons" },
+		{ "path": "../is-shallow-equal" }
+	],
+	"include": [ "src/**/*" ]
+}