WordPress · adamziel · Feb 6, 2023 · Feb 3, 2023 · Feb 3, 2023 · Feb 6, 2023
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -19,7 +19,8 @@
 		"npm": ">=6.9.0 <7"
 	},
 	"config": {
-		"IS_GUTENBERG_PLUGIN": true
+		"IS_GUTENBERG_PLUGIN": true,
+		"ALLOW_EXPERIMENT_REREGISTRATION": true
 	},
 	"dependencies": {
 		"@wordpress/a11y": "file:packages/a11y",

@@ -21,7 +21,7 @@ import { store as blockEditorStore } from '../../store';
 import BlockPopover from '../block-popover';
 import useBlockToolbarPopoverProps from './use-block-toolbar-popover-props';
 import Inserter from '../inserter';
-import { unlock } from '../../experiments';
+import { unlock } from '../../lock-unlock';
 
 function selector( select ) {
 	const {

@@ -12,7 +12,7 @@ import { forwardRef, useEffect, useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import { unlock } from '../../experiments';
+import { unlock } from '../../lock-unlock';
 import ListViewBlockSelectButton from './block-select-button';
 import BlockDraggable from '../block-draggable';
 import { store as blockEditorStore } from '../../store';

@@ -11,7 +11,7 @@ import withRegistryProvider from './with-registry-provider';
 import useBlockSync from './use-block-sync';
 import { store as blockEditorStore } from '../../store';
 import { BlockRefsProvider } from './block-refs-provider';
-import { unlock } from '../../experiments';
+import { unlock } from '../../lock-unlock';
 
 /** @typedef {import('@wordpress/data').WPDataRegistry} WPDataRegistry */
 

@@ -1,21 +1,11 @@
-/**
- * WordPress dependencies
- */
-import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/experiments';
-
 /**
  * Internal dependencies
  */
 import * as globalStyles from './components/global-styles';
 import { ExperimentalBlockEditorProvider } from './components/provider';
+import { lock } from './lock-unlock';
 import OffCanvasEditor from './components/off-canvas-editor';
 
-export const { lock, unlock } =
-	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
-		'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
-		'@wordpress/block-editor'
-	);
-
 /**
  * Experimental @wordpress/block-editor APIs.
  */

@@ -59,7 +59,7 @@ import {
 } from './child-layout';
 import useSetting from '../components/use-setting';
 import { store as blockEditorStore } from '../store';
-import { unlock } from '../experiments';
+import { unlock } from '../lock-unlock';
 
 export const DIMENSIONS_SUPPORT_KEY = 'dimensions';
 export const SPACING_SUPPORT_KEY = 'spacing';

@@ -8,7 +8,10 @@ import classnames from 'classnames';
  */
 import { __, sprintf } from '@wordpress/i18n';
 import { getBlockSupport, hasBlockSupport } from '@wordpress/blocks';
-import { BaseControl, CustomSelectControl } from '@wordpress/components';
+import {
+	BaseControl,
+	experiments as componentsExperiments,
+} from '@wordpress/components';
 import { createHigherOrderComponent, useInstanceId } from '@wordpress/compose';
 import { useSelect } from '@wordpress/data';
 import {
@@ -26,8 +29,11 @@ import BlockList from '../components/block-list';
 import useSetting from '../components/use-setting';
 import InspectorControls from '../components/inspector-controls';
 import { cleanEmptyObject } from './utils';
+import { unlock } from '../lock-unlock';
 import { store as blockEditorStore } from '../store';
 
+const { CustomSelectControl } = unlock( componentsExperiments );
+
 const POSITION_SUPPORT_KEY = 'position';
 
 const OPTION_CLASSNAME =

@@ -0,0 +1,10 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/experiments';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
+		'@wordpress/block-editor'
+	);
@@ -12,7 +12,7 @@ import * as privateActions from './private-actions';
 import * as privateSelectors from './private-selectors';
 import * as actions from './actions';
 import { STORE_NAME } from './constants';
-import { unlock } from '../experiments';
+import { unlock } from '../lock-unlock';
 
 /**
  * Block editor data store configuration.

@@ -16,6 +16,7 @@
 		{ "path": "../dom" },
 		{ "path": "../element" },
 		{ "path": "../escape-html" },
+		{ "path": "../experiments" },
 		{ "path": "../hooks" },
 		{ "path": "../html-entities" },
 		{ "path": "../i18n" },

@@ -21,6 +21,7 @@
 		{ "path": "../dom" },
 		{ "path": "../element" },
 		{ "path": "../escape-html" },
+		{ "path": "../experiments" },
 		{ "path": "../hooks" },
 		{ "path": "../html-entities" },
 		{ "path": "../i18n" },

@@ -45,6 +45,7 @@
 		"@wordpress/dom": "file:../dom",
 		"@wordpress/element": "file:../element",
 		"@wordpress/escape-html": "file:../escape-html",
+		"@wordpress/experiments": "file:../experiments",
 		"@wordpress/hooks": "file:../hooks",
 		"@wordpress/html-entities": "file:../html-entities",
 		"@wordpress/i18n": "file:../i18n",

@@ -257,3 +257,12 @@ export default function CustomSelectControl( props ) {
 		</div>
 	);
 }
+
+export function StableCustomSelectControl( props ) {
+	return (
+		<CustomSelectControl
+			{ ...props }
+			__experimentalShowSelectedHint={ false }
+		/>
+	);
+}
@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import CustomSelectControl from '../';
+import CustomSelectControl from '..';
 
 export default {
 	title: 'Components/CustomSelectControl',

@@ -4,9 +4,9 @@
 import { render, fireEvent, screen } from '@testing-library/react';
 
 /**
- * WordPress dependencies
+ * Internal dependencies
  */
-import { CustomSelectControl } from '@wordpress/components';
+import CustomSelectControl from '..';
 
 describe( 'CustomSelectControl', () => {
 	it( 'Captures the keypress event and does not let it propagate', () => {

@@ -0,0 +1,20 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/experiments';
+
+/**
+ * Internal dependencies
+ */
+import { default as CustomSelectControl } from './custom-select-control';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
+		'@wordpress/components'
+	);
+
+export const experiments = {};
+lock( experiments, {
+	CustomSelectControl,
+} );
@@ -59,7 +59,7 @@ export {
 	useCompositeState as __unstableUseCompositeState,
 } from './composite';
 export { ConfirmDialog as __experimentalConfirmDialog } from './confirm-dialog';
-export { default as CustomSelectControl } from './custom-select-control';
+export { StableCustomSelectControl as CustomSelectControl } from './custom-select-control';
 export { default as Dashicon } from './dashicon';
 export { default as DateTimePicker, DatePicker, TimePicker } from './date-time';
 export { default as __experimentalDimensionControl } from './dimension-control';
@@ -212,3 +212,6 @@ export {
 } from './higher-order/with-focus-return';
 export { default as withNotices } from './higher-order/with-notices';
 export { default as withSpokenMessages } from './higher-order/with-spoken-messages';
+
+// Experiments.
+export { experiments } from './experiments';
@@ -25,6 +25,7 @@
 		{ "path": "../dom" },
 		{ "path": "../element" },
 		{ "path": "../escape-html" },
+		{ "path": "../experiments" },
 		{ "path": "../hooks" },
 		{ "path": "../html-entities" },
 		{ "path": "../i18n" },

@@ -10,6 +10,7 @@
 		{ "path": "../compose" },
 		{ "path": "../deprecated" },
 		{ "path": "../element" },
+		{ "path": "../experiments" },
 		{ "path": "../is-shallow-equal" },
 		{ "path": "../priority-queue" },
 		{ "path": "../redux-routine" }

diff --git a/packages/experiments/package.json b/packages/experiments/package.json
@@ -25,6 +25,7 @@
 	"main": "build/index.js",
 	"module": "build-module/index.js",
 	"react-native": "src/index",
+	"types": "build-types",
 	"sideEffects": false,
 	"dependencies": {
 		"@babel/runtime": "^7.16.0"

diff --git a/packages/experiments/src/implementation.js b/packages/experiments/src/implementation.js
@@ -10,20 +10,23 @@
  * The list of core modules allowed to opt-in to the experimental APIs.
  */
 const CORE_MODULES_USING_EXPERIMENTS = [
-	'@wordpress/data',
-	'@wordpress/editor',
-	'@wordpress/blocks',
 	'@wordpress/block-editor',
+	'@wordpress/block-library',
+	'@wordpress/blocks',
+	'@wordpress/components',
 	'@wordpress/customize-widgets',
-	'@wordpress/edit-site',
+	'@wordpress/data',
 	'@wordpress/edit-post',
+	'@wordpress/edit-site',
 	'@wordpress/edit-widgets',
-	'@wordpress/block-library',
+	'@wordpress/editor',
 ];
 
 /**
  * A list of core modules that already opted-in to
  * the experiments package.
+ *
+ * @type {string[]}
  */
 const registeredExperiments = [];
 
@@ -44,6 +47,24 @@ const registeredExperiments = [];
 const requiredConsent =
 	'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.';
 
+/** @type {boolean} */
+let allowReRegistration;
+// Use try/catch to force "false" if the environment variable is not explicitly
+// set to true (e.g. when building WordPress core).
+try {
+	allowReRegistration = process.env.ALLOW_EXPERIMENT_REREGISTRATION ?? false;
+} catch ( error ) {
+	allowReRegistration = false;
+}
+
+/**
+ * Called by a @wordpress package wishing to opt-in to accessing or exposing
+ * private experimental APIs.
+ *
+ * @param {string} consent    The consent string.
+ * @param {string} moduleName The name of the module that is opting in.
+ * @return {{lock: typeof lock, unlock: typeof unlock}} An object containing the lock and unlock functions.
+ */
 export const __dangerousOptInToUnstableAPIsOnlyForCoreModules = (
 	consent,
 	moduleName
@@ -57,7 +78,13 @@ export const __dangerousOptInToUnstableAPIsOnlyForCoreModules = (
 				'your product will inevitably break on one of the next WordPress releases.'
 		);
 	}
-	if ( registeredExperiments.includes( moduleName ) ) {
+	if (
+		! allowReRegistration &&
+		registeredExperiments.includes( moduleName )
+	) {
+		// This check doesn't play well with Story Books / Hot Module Reloading
+		// and isn't included in the Gutenberg plugin. It only matters in the
+		// WordPress core release.
 		throw new Error(
 			`You tried to opt-in to unstable APIs as module "${ moduleName }" which is already registered. ` +
 				'This feature is only for JavaScript modules shipped with WordPress core. ' +
@@ -104,8 +131,8 @@ export const __dangerousOptInToUnstableAPIsOnlyForCoreModules = (
  * // { a: 1 }
  * ```
  *
- * @param {Object|Function} object      The object to bind the private data to.
- * @param {any}             privateData The private data to bind to the object.
+ * @param {any} object      The object to bind the private data to.
+ * @param {any} privateData The private data to bind to the object.
  */
 function lock( object, privateData ) {
 	if ( ! object ) {

diff --git a/packages/experiments/tsconfig.json b/packages/experiments/tsconfig.json
@@ -0,0 +1,9 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"rootDir": "src",
+		"declarationDir": "build-types",
+		"types": [ "gutenberg-env" ]
+	},
+	"include": [ "src/**/*" ]
+}
diff --git a/storybook/main.js b/storybook/main.js
@@ -5,8 +5,6 @@ const stories = [
 	'../packages/icons/src/**/stories/*.@(js|tsx|mdx)',
 ].filter( Boolean );
 
-const customEnvVariables = {};
-
 module.exports = {
 	core: {
 		builder: 'webpack5',
@@ -30,20 +28,10 @@ module.exports = {
 		emotionAlias: false,
 		storyStoreV7: true,
 	},
-	// Workaround:
-	// https://github.com/storybookjs/storybook/issues/12270
-	webpackFinal: async ( config ) => {
-		// Find the DefinePlugin.
-		const plugin = config.plugins.find( ( p ) => {
-			return p.definitions && p.definitions[ 'process.env' ];
-		} );
-		// Add custom env variables.
-		Object.keys( customEnvVariables ).forEach( ( key ) => {
-			plugin.definitions[ 'process.env' ][ key ] = JSON.stringify(
-				customEnvVariables[ key ]
-			);
-		} );
-
-		return config;
-	},
+	env: ( config ) => ( {
+		...config,
+		// Inject the `ALLOW_EXPERIMENT_REREGISTRATION` global, used by
+		// @wordpress/experiments.
+		ALLOW_EXPERIMENT_REREGISTRATION: true,
+	} ),
 };
diff --git a/test/native/setup.js b/test/native/setup.js
@@ -8,6 +8,14 @@ import { Image, NativeModules as RNNativeModules } from 'react-native';
 // testing environment: https://github.com/facebook/react-native/blob/6c19dc3266b84f47a076b647a1c93b3c3b69d2c5/Libraries/Core/setUpNavigator.js#L17
 global.navigator = global.navigator ?? {};
 
+/**
+ * Whether to allow the same experiment to be registered multiple times.
+ * This is useful for development purposes, but should be set to false
+ * during the unit tests to ensure the Gutenberg plugin can be cleanly
+ * merged into WordPress core where this is false.
+ */
+global.process.env.ALLOW_EXPERIMENT_REREGISTRATION = true;
+
 // Set up the app runtime globals for the test environment, which includes
 // modifying the above `global.navigator`
 require( '../../packages/react-native-editor/src/globals' );

diff --git a/test/unit/config/is-gutenberg-plugin.js → test/unit/config/gutenberg-env.js b/test/unit/config/is-gutenberg-plugin.js → test/unit/config/gutenberg-env.js
@@ -22,4 +22,11 @@ global.process.env = {
 	// eslint-disable-next-line @wordpress/is-gutenberg-plugin
 	IS_GUTENBERG_PLUGIN:
 		String( process.env.npm_package_config_IS_GUTENBERG_PLUGIN ) === 'true',
+	/**
+	 * Whether to allow the same experiment to be registered multiple times.
+	 * This is useful for development purposes, but should be set to false
+	 * during the unit tests to ensure the Gutenberg plugin can be cleanly
+	 * merged into WordPress core where this is false.
+	 */
+	ALLOW_EXPERIMENT_REREGISTRATION: false,
 };