Introduce ExperimentalBlockEditorProvider

docs/contributors/code/coding-guidelines.md

@@ -441,6 +441,19 @@ export function MyComponent() {
 }
 ```
 
+#### Experimental editor settings
+
+WordPress extenders cannot update the experimental block settings on their own. The `updateSettings()` actions of the `@wordpress/block-editor` store will filter out all the settings that are **not** a part of the public API. The only way to actually store them is via private action. `__experimentalUpdateSettings()`.
+
+To privatize a block editor setting, add it to the `privateSettings` list in [/packages/block-editor/src/store/actions.js](/packages/block-editor/src/store/actions.js):
+
+```js
+const privateSettings = [
+	'__unstableInserterMediaCategories',
+	// List a block editor setting here to make it private
+];
+```
+
 #### Experimental block.json and theme.json APIs
 
 As of today, there is no way to restrict the `block.json` and `theme.json` APIs

packages/block-editor/src/components/block-mover/stories/index.js

@@ -11,7 +11,7 @@ import { Toolbar } from '@wordpress/components';
  * Internal dependencies
  */
 import BlockMover from '../';
-import BlockEditorProvider from '../../provider';
+import { ExperimentalBlockEditorProvider } from '../../provider';
 import { store as blockEditorStore } from '../../../store';
 
 registerCoreBlocks();
@@ -35,9 +35,9 @@ function Provider( { children } ) {
 
 	return (
 		<div style={ wrapperStyle }>
-			<BlockEditorProvider value={ blocks }>
+			<ExperimentalBlockEditorProvider value={ blocks }>
 				{ children }
-			</BlockEditorProvider>
+			</ExperimentalBlockEditorProvider>
 		</div>
 	);
 }

packages/block-editor/src/components/block-preview/index.js

@@ -14,7 +14,7 @@ import deprecated from '@wordpress/deprecated';
 /**
  * Internal dependencies
  */
-import BlockEditorProvider from '../provider';
+import { ExperimentalBlockEditorProvider } from '../provider';
 import AutoHeightBlockPreview from './auto';
 import { store as blockEditorStore } from '../../store';
 import { BlockListItems } from '../block-list';
@@ -66,13 +66,16 @@ export function BlockPreview( {
 	}
 
 	return (
-		<BlockEditorProvider value={ renderedBlocks } settings={ settings }>
+		<ExperimentalBlockEditorProvider
+			value={ renderedBlocks }
+			settings={ settings }
+		>
 			<AutoHeightBlockPreview
 				viewportWidth={ viewportWidth }
 				minHeight={ minHeight }
 				additionalStyles={ additionalStyles }
 			/>
-		</BlockEditorProvider>
+		</ExperimentalBlockEditorProvider>
 	);
 }
 
@@ -126,12 +129,15 @@ export function useBlockPreview( {
 	);
 
 	const children = (
-		<BlockEditorProvider value={ renderedBlocks } settings={ settings }>
+		<ExperimentalBlockEditorProvider
+			value={ renderedBlocks }
+			settings={ settings }
+		>
 			<BlockListItems
 				renderAppender={ false }
 				__experimentalLayout={ __experimentalLayout }
 			/>
-		</BlockEditorProvider>
+		</ExperimentalBlockEditorProvider>
 	);
 
 	return {

packages/block-editor/src/components/inserter/stories/index.js

@@ -2,7 +2,7 @@
  * Internal dependencies
  */
 import BlockLibrary from '../library';
-import BlockEditorProvider from '../../provider';
+import { ExperimentalBlockEditorProvider } from '../../provider';
 import { patternCategories, patterns, reusableBlocks } from './utils/fixtures';
 import Inserter from '../';
 
@@ -16,11 +16,11 @@ export const libraryWithoutPatterns = () => {
 		display: 'inline-block',
 	};
 	return (
-		<BlockEditorProvider>
+		<ExperimentalBlockEditorProvider>
 			<div style={ wrapperStyle }>
 				<BlockLibrary showInserterHelpPanel />
 			</div>
-		</BlockEditorProvider>
+		</ExperimentalBlockEditorProvider>
 	);
 };
 
@@ -32,7 +32,7 @@ export const libraryWithPatterns = () => {
 		display: 'inline-block',
 	};
 	return (
-		<BlockEditorProvider
+		<ExperimentalBlockEditorProvider
 			settings={ {
 				__experimentalBlockPatternCategories: patternCategories,
 				__experimentalBlockPatterns: patterns,
@@ -41,7 +41,7 @@ export const libraryWithPatterns = () => {
 			<div style={ wrapperStyle }>
 				<BlockLibrary showInserterHelpPanel />
 			</div>
-		</BlockEditorProvider>
+		</ExperimentalBlockEditorProvider>
 	);
 };
 
@@ -53,7 +53,7 @@ export const libraryWithPatternsAndReusableBlocks = () => {
 		display: 'inline-block',
 	};
 	return (
-		<BlockEditorProvider
+		<ExperimentalBlockEditorProvider
 			settings={ {
 				__experimentalBlockPatternCategories: patternCategories,
 				__experimentalBlockPatterns: patterns,
@@ -63,7 +63,7 @@ export const libraryWithPatternsAndReusableBlocks = () => {
 			<div style={ wrapperStyle }>
 				<BlockLibrary showInserterHelpPanel />
 			</div>
-		</BlockEditorProvider>
+		</ExperimentalBlockEditorProvider>
 	);
 };
 
@@ -75,7 +75,7 @@ export const quickInserter = () => {
 		display: 'inline-block',
 	};
 	return (
-		<BlockEditorProvider
+		<ExperimentalBlockEditorProvider
 			settings={ {
 				__experimentalBlockPatternCategories: patternCategories,
 				__experimentalBlockPatterns: patterns,
@@ -85,6 +85,6 @@ export const quickInserter = () => {
 			<div style={ wrapperStyle }>
 				<Inserter __experimentalIsQuick />
 			</div>
-		</BlockEditorProvider>
+		</ExperimentalBlockEditorProvider>
 	);
 };

packages/block-editor/src/components/provider/index.js

@@ -11,24 +11,43 @@ 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';
 
 /** @typedef {import('@wordpress/data').WPDataRegistry} WPDataRegistry */
 
-function BlockEditorProvider( props ) {
-	const { children, settings } = props;
+export const ExperimentalBlockEditorProvider = withRegistryProvider(
+	( props ) => {
+		const { children, settings, stripExperimentalSettings = false } = props;
 
-	const { updateSettings } = useDispatch( blockEditorStore );
-	useEffect( () => {
-		updateSettings( {
-			...settings,
-			__internalIsInitialized: true,
-		} );
-	}, [ settings ] );
+		const { __experimentalUpdateSettings } = unlock(
+			useDispatch( blockEditorStore )
+		);
+		useEffect( () => {
+			__experimentalUpdateSettings(
+				{
+					...settings,
+					__internalIsInitialized: true,
+				},
+				stripExperimentalSettings
+			);
+		}, [ settings ] );
 
-	// Syncs the entity provider with changes in the block-editor store.
-	useBlockSync( props );
+		// Syncs the entity provider with changes in the block-editor store.
+		useBlockSync( props );
 
-	return <BlockRefsProvider>{ children }</BlockRefsProvider>;
-}
+		return <BlockRefsProvider>{ children }</BlockRefsProvider>;
+	}
+);
 
-export default withRegistryProvider( BlockEditorProvider );
+export const BlockEditorProvider = ( props ) => {
+	return (
+		<ExperimentalBlockEditorProvider
+			{ ...props }
+			stripExperimentalSettings={ true }
+		>
+			{ props.children }
+		</ExperimentalBlockEditorProvider>
+	);
+};
+
+export default BlockEditorProvider;

packages/block-editor/src/components/provider/index.native.js

@@ -14,7 +14,7 @@ import { BlockRefsProvider } from './block-refs-provider';
 
 /** @typedef {import('@wordpress/data').WPDataRegistry} WPDataRegistry */
 
-function BlockEditorProvider( props ) {
+const BlockEditorProvider = withRegistryProvider( function ( props ) {
 	const { children, settings } = props;
 
 	const { updateSettings } = useDispatch( blockEditorStore );
@@ -26,6 +26,7 @@ function BlockEditorProvider( props ) {
 	useBlockSync( props );
 
 	return <BlockRefsProvider>{ children }</BlockRefsProvider>;
-}
+} );
 
-export default withRegistryProvider( BlockEditorProvider );
+export default BlockEditorProvider;
+export { BlockEditorProvider as ExperimentalBlockEditorProvider };

packages/block-editor/src/components/provider/test/experimental-provider.js

@@ -0,0 +1,98 @@
+/**
+ * External dependencies
+ */
+import { render } from '@testing-library/react';
+/**
+ * WordPress dependencies
+ */
+import { useRegistry } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { BlockEditorProvider, ExperimentalBlockEditorProvider } from '../';
+import { store as blockEditorStore } from '../../../store';
+
+const HasEditorSetting = ( props ) => {
+	const registry = useRegistry();
+	if ( props.setRegistry ) {
+		props.setRegistry( registry );
+	}
+	return <p>Test.</p>;
+};
+
+describe( 'BlockEditorProvider', () => {
+	let registry;
+	const setRegistry = ( reg ) => {
+		registry = reg;
+	};
+	beforeEach( () => {
+		registry = undefined;
+	} );
+	it( 'should strip experimental settings', async () => {
+		render(
+			<BlockEditorProvider
+				settings={ {
+					__unstableInserterMediaCategories: true,
+				} }
+			>
+				<HasEditorSetting setRegistry={ setRegistry } />
+			</BlockEditorProvider>
+		);
+		const settings = registry.select( blockEditorStore ).getSettings();
+		expect( settings ).not.toHaveProperty(
+			'__unstableInserterMediaCategories'
+		);
+	} );
+	it( 'should preserve stable settings', async () => {
+		render(
+			<BlockEditorProvider
+				settings={ {
+					stableSetting: 'https://example.com',
+				} }
+			>
+				<HasEditorSetting setRegistry={ setRegistry } />
+			</BlockEditorProvider>
+		);
+		const settings = registry.select( blockEditorStore ).getSettings();
+		expect( settings ).toHaveProperty( 'stableSetting' );
+	} );
+} );
+
+describe( 'ExperimentalBlockEditorProvider', () => {
+	let registry;
+	const setRegistry = ( reg ) => {
+		registry = reg;
+	};
+	beforeEach( () => {
+		registry = undefined;
+	} );
+	it( 'should preserve experimental settings', async () => {
+		render(
+			<ExperimentalBlockEditorProvider
+				settings={ {
+					__unstableInserterMediaCategories: true,
+				} }
+			>
+				<HasEditorSetting setRegistry={ setRegistry } />
+			</ExperimentalBlockEditorProvider>
+		);
+		const settings = registry.select( blockEditorStore ).getSettings();
+		expect( settings ).toHaveProperty(
+			'__unstableInserterMediaCategories'
+		);
+	} );
+	it( 'should preserve stable settings', async () => {
+		render(
+			<ExperimentalBlockEditorProvider
+				settings={ {
+					stableSetting: 'https://example.com',
+				} }
+			>
+				<HasEditorSetting setRegistry={ setRegistry } />
+			</ExperimentalBlockEditorProvider>
+		);
+		const settings = registry.select( blockEditorStore ).getSettings();
+		expect( settings ).toHaveProperty( 'stableSetting' );
+	} );
+} );

packages/block-editor/src/components/provider/test/use-block-sync.js

@@ -14,7 +14,17 @@ import { render } from '@testing-library/react';
 import useBlockSync from '../use-block-sync';
 import withRegistryProvider from '../with-registry-provider';
 import * as blockEditorActions from '../../../store/actions';
+
 import { store as blockEditorStore } from '../../../store';
+jest.mock( '../../../store/actions', () => {
+	const actions = jest.requireActual( '../../../store/actions' );
+	return {
+		...actions,
+		resetBlocks: jest.fn( actions.resetBlocks ),
+		replaceInnerBlocks: jest.fn( actions.replaceInnerBlocks ),
+		setHasControlledInnerBlocks: jest.fn( actions.replaceInnerBlocks ),
+	};
+} );
 
 const TestWrapper = withRegistryProvider( ( props ) => {
 	if ( props.setRegistry ) {