Stabilize isPreviewMode flag (#66149)

zaguiini · web-flow · commit d9e7ee7156d6 · 2024-10-22T14:34:09.000Z
* Introduce stable isPreviewMode key and deprecate __unstableIsPreviewMode

* Expose stable isPreviewMode as registry values

* Use isPreviewMode instead of __unstableIsPreviewMode when accessing the setting

* Access isPreviewMode directly from getSettings instead of through private symbol within RichText block

* Revert private isPreviewMode changes

* Add __unstableIsPreviewMode getter within settings reducer

* Remove all other __unstableIsPreviewMode definitions

* Define deprecation setter with Object.defineProperty to avoid eager getting when spreading the settings object

* Use WP version within deprecation note

* Add deprecation notice when trying to set __unstableIsPreviewMode in updateSettings

* Add test to assert deprecated getters are passed to sub registry when defining a nested provider

* Move deprecated setter logic to __experimentalUpdateSettings
diff --git a/packages/block-editor/src/components/block-list/block.js b/packages/block-editor/src/components/block-list/block.js
@@ -629,8 +629,7 @@ function BlockListBlockProvider( props ) {
 			const attributes = getBlockAttributes( clientId );
 			const { name: blockName, isValid } = blockWithoutAttributes;
 			const blockType = getBlockType( blockName );
-			const { supportsLayout, __unstableIsPreviewMode: isPreviewMode } =
-				getSettings();
+			const { supportsLayout, isPreviewMode } = getSettings();
 			const hasLightBlockWrapper = blockType?.apiVersion > 1;
 			const previewContext = {
 				isPreviewMode,
diff --git a/packages/block-editor/src/components/block-list/index.js b/packages/block-editor/src/components/block-list/index.js
@@ -187,7 +187,7 @@ function Items( {
 
 			const _order = getBlockOrder( rootClientId );
 
-			if ( getSettings().__unstableIsPreviewMode ) {
+			if ( getSettings().isPreviewMode ) {
 				return {
 					order: _order,
 					selectedBlocks: EMPTY_ARRAY,
diff --git a/packages/block-editor/src/components/block-preview/index.js b/packages/block-editor/src/components/block-preview/index.js
@@ -59,7 +59,7 @@ export function BlockPreview( {
 		() => ( {
 			...originalSettings,
 			focusMode: false, // Disable "Spotlight mode".
-			__unstableIsPreviewMode: true,
+			isPreviewMode: true,
 		} ),
 		[ originalSettings ]
 	);
@@ -124,7 +124,7 @@ export function useBlockPreview( { blocks, props = {}, layout } ) {
 			...originalSettings,
 			styles: undefined, // Clear styles included by the parent settings, as they are already output by the parent's EditorStyles.
 			focusMode: false, // Disable "Spotlight mode".
-			__unstableIsPreviewMode: true,
+			isPreviewMode: true,
 		} ),
 		[ originalSettings ]
 	);
diff --git a/packages/block-editor/src/components/iframe/index.js b/packages/block-editor/src/components/iframe/index.js
@@ -117,7 +117,7 @@ function Iframe( {
 		const settings = getSettings();
 		return {
 			resolvedAssets: settings.__unstableResolvedAssets,
-			isPreviewMode: settings.__unstableIsPreviewMode,
+			isPreviewMode: settings.isPreviewMode,
 		};
 	}, [] );
 	const { styles = '', scripts = '' } = resolvedAssets;
diff --git a/packages/block-editor/src/components/provider/index.js b/packages/block-editor/src/components/provider/index.js
@@ -46,9 +46,7 @@ export const ExperimentalBlockEditorProvider = withRegistryProvider(
 
 		return (
 			<SlotFillProvider passthrough>
-				{ ! settings?.__unstableIsPreviewMode && (
-					<KeyboardShortcuts.Register />
-				) }
+				{ ! settings?.isPreviewMode && <KeyboardShortcuts.Register /> }
 				<BlockRefsProvider>{ children }</BlockRefsProvider>
 			</SlotFillProvider>
 		);
diff --git a/packages/block-editor/src/components/provider/test/experimental-provider.js b/packages/block-editor/src/components/provider/test/experimental-provider.js
@@ -5,7 +5,7 @@ import { render } from '@testing-library/react';
 /**
  * WordPress dependencies
  */
-import { useRegistry } from '@wordpress/data';
+import { useRegistry, useSelect } from '@wordpress/data';
 
 /**
  * Internal dependencies
@@ -21,6 +21,20 @@ const HasEditorSetting = ( props ) => {
 	return <p>Test.</p>;
 };
 
+const PreviewModeGetter = () => {
+	const previewModeKeys = useSelect( ( select ) => {
+		const { getSettings } = select( blockEditorStore );
+		const settings = getSettings();
+		return {
+			// This property will be removed in the future. There is a test that asserts we're throwing a deprecation warning.
+			__unstableIsPreviewMode: settings.__unstableIsPreviewMode,
+			isPreviewMode: settings.isPreviewMode,
+		};
+	}, [] );
+
+	return <>{ JSON.stringify( previewModeKeys ) }</>;
+};
+
 describe( 'BlockEditorProvider', () => {
 	let registry;
 	const setRegistry = ( reg ) => {
@@ -58,6 +72,34 @@ describe( 'BlockEditorProvider', () => {
 		const settings = registry.select( blockEditorStore ).getSettings();
 		expect( settings ).toHaveProperty( 'stableSetting' );
 	} );
+	it( 'preserves deprecated getters incoming from the settings reducer', async () => {
+		const consoleWarn = jest
+			.spyOn( global.console, 'warn' )
+			.mockImplementation();
+
+		const { container } = render(
+			<BlockEditorProvider
+				settings={ {
+					isPreviewMode: true,
+				} }
+			>
+				<PreviewModeGetter />
+			</BlockEditorProvider>
+		);
+
+		expect( container ).toHaveTextContent(
+			JSON.stringify( {
+				__unstableIsPreviewMode: true,
+				isPreviewMode: true,
+			} )
+		);
+
+		expect( consoleWarn ).toHaveBeenCalledWith(
+			'__unstableIsPreviewMode is deprecated since version 6.8. Please use isPreviewMode instead.'
+		);
+
+		consoleWarn.mockRestore();
+	} );
 } );
 
 describe( 'ExperimentalBlockEditorProvider', () => {
diff --git a/packages/block-editor/src/store/defaults.js b/packages/block-editor/src/store/defaults.js
@@ -167,7 +167,8 @@ export const SETTINGS_DEFAULTS = {
 	__mobileEnablePageTemplates: false,
 	__experimentalBlockPatterns: [],
 	__experimentalBlockPatternCategories: [],
-	__unstableIsPreviewMode: false,
+
+	isPreviewMode: false,
 
 	// These settings will be completely revamped in the future.
 	// The goal is to evolve this into an API which will instruct
diff --git a/packages/block-editor/src/store/private-actions.js b/packages/block-editor/src/store/private-actions.js
@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import { Platform } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 import { speak } from '@wordpress/a11y';
 import { __ } from '@wordpress/i18n';
 
@@ -41,14 +42,32 @@ export function __experimentalUpdateSettings(
 	settings,
 	{ stripExperimentalSettings = false, reset = false } = {}
 ) {
-	let cleanSettings = settings;
+	let incomingSettings = settings;
+
+	if ( Object.hasOwn( incomingSettings, '__unstableIsPreviewMode' ) ) {
+		deprecated(
+			"__unstableIsPreviewMode argument in wp.data.dispatch('core/block-editor').updateSettings",
+			{
+				since: '6.8',
+				alternative: 'isPreviewMode',
+			}
+		);
+
+		incomingSettings = { ...incomingSettings };
+		incomingSettings.isPreviewMode =
+			incomingSettings.__unstableIsPreviewMode;
+		delete incomingSettings.__unstableIsPreviewMode;
+	}
+
+	let cleanSettings = incomingSettings;
+
 	// There are no plugins in the mobile apps, so there is no
 	// need to strip the experimental settings:
 	if ( stripExperimentalSettings && Platform.OS === 'web' ) {
 		cleanSettings = {};
-		for ( const key in settings ) {
+		for ( const key in incomingSettings ) {
 			if ( ! privateSettings.includes( key ) ) {
-				cleanSettings[ key ] = settings[ key ];
+				cleanSettings[ key ] = incomingSettings[ key ];
 			}
 		}
 	}
diff --git a/packages/block-editor/src/store/reducer.js b/packages/block-editor/src/store/reducer.js
@@ -8,6 +8,7 @@ import fastDeepEqual from 'fast-deep-equal/es6';
  */
 import { pipe } from '@wordpress/compose';
 import { combineReducers, select } from '@wordpress/data';
+import deprecated from '@wordpress/deprecated';
 import { store as blocksStore } from '@wordpress/blocks';
 /**
  * Internal dependencies
@@ -1660,17 +1661,30 @@ export function template( state = { isValid: true }, action ) {
  */
 export function settings( state = SETTINGS_DEFAULTS, action ) {
 	switch ( action.type ) {
-		case 'UPDATE_SETTINGS':
-			if ( action.reset ) {
-				return {
-					...SETTINGS_DEFAULTS,
-					...action.settings,
-				};
-			}
-			return {
-				...state,
-				...action.settings,
-			};
+		case 'UPDATE_SETTINGS': {
+			const updatedSettings = action.reset
+				? {
+						...SETTINGS_DEFAULTS,
+						...action.settings,
+				  }
+				: {
+						...state,
+						...action.settings,
+				  };
+
+			Object.defineProperty( updatedSettings, '__unstableIsPreviewMode', {
+				get() {
+					deprecated( '__unstableIsPreviewMode', {
+						since: '6.8',
+						alternative: 'isPreviewMode',
+					} );
+
+					return this.isPreviewMode;
+				},
+			} );
+
+			return updatedSettings;
+		}
 	}
 
 	return state;
diff --git a/packages/block-editor/src/store/test/actions.js b/packages/block-editor/src/store/test/actions.js
@@ -1125,6 +1125,47 @@ describe( 'actions', () => {
 		} );
 	} );
 
+	describe( 'updateSettings', () => {
+		it( 'warns when setting the deprecated __unstableIsPreviewMode property and sets the stable property instead', () => {
+			const consoleWarn = jest
+				.spyOn( global.console, 'warn' )
+				.mockImplementation();
+
+			const store = createRegistry().registerStore(
+				blockEditorStoreName,
+				{
+					actions,
+					selectors,
+					reducer,
+				}
+			);
+
+			store.dispatch(
+				updateSettings( {
+					__unstableIsPreviewMode: true,
+				} )
+			);
+
+			expect( consoleWarn ).toHaveBeenCalledWith(
+				"__unstableIsPreviewMode argument in wp.data.dispatch('core/block-editor').updateSettings is deprecated since version 6.8. Please use isPreviewMode instead."
+			);
+
+			consoleWarn.mockClear();
+
+			expect( store.getState().settings.__unstableIsPreviewMode ).toBe(
+				true
+			);
+
+			expect( store.getState().settings.isPreviewMode ).toBe( true );
+
+			expect( consoleWarn ).toHaveBeenCalledWith(
+				'__unstableIsPreviewMode is deprecated since version 6.8. Please use isPreviewMode instead.'
+			);
+
+			consoleWarn.mockRestore();
+		} );
+	} );
+
 	describe( 'registerInserterMediaCategory', () => {
 		describe( 'should log errors when invalid', () => {
 			it( 'valid object', () => {
diff --git a/packages/block-editor/src/store/test/reducer.js b/packages/block-editor/src/store/test/reducer.js
@@ -32,6 +32,7 @@ import {
 	insertionPoint,
 	template,
 	blockListSettings,
+	settings,
 	lastBlockAttributesChange,
 	lastBlockInserted,
 	blockEditingModes,
@@ -3070,6 +3071,28 @@ describe( 'state', () => {
 		} );
 	} );
 
+	describe( 'settings', () => {
+		it( 'should warn about __unstableIsPreviewMode deprecation', () => {
+			const consoleWarn = jest
+				.spyOn( global.console, 'warn' )
+				.mockImplementation();
+
+			const settingsObject = settings( undefined, {
+				type: 'UPDATE_SETTINGS',
+				reset: true,
+			} );
+
+			expect( settingsObject.__unstableIsPreviewMode ).toBeDefined();
+			expect( settingsObject.isPreviewMode ).toBeDefined();
+
+			expect( consoleWarn ).toHaveBeenCalledWith(
+				'__unstableIsPreviewMode is deprecated since version 6.8. Please use isPreviewMode instead.'
+			);
+
+			consoleWarn.mockRestore();
+		} );
+	} );
+
 	describe( 'blockListSettings', () => {
 		it( 'should add new settings', () => {
 			const original = deepFreeze( {} );
diff --git a/packages/edit-site/src/components/block-editor/use-site-editor-settings.js b/packages/edit-site/src/components/block-editor/use-site-editor-settings.js
@@ -72,7 +72,7 @@ export function useSpecificEditorSettings() {
 			defaultRenderingMode,
 			onNavigateToEntityRecord,
 			onNavigateToPreviousEntityRecord,
-			__unstableIsPreviewMode: canvas === 'view',
+			isPreviewMode: canvas === 'view',
 		};
 	}, [
 		settings,
diff --git a/packages/edit-site/src/components/page-patterns/use-pattern-settings.js b/packages/edit-site/src/components/page-patterns/use-pattern-settings.js
@@ -43,7 +43,7 @@ export default function usePatternSettings() {
 		return {
 			...restStoredSettings,
 			__experimentalBlockPatterns: blockPatterns,
-			__unstableIsPreviewMode: true,
+			isPreviewMode: true,
 		};
 	}, [ storedSettings, blockPatterns ] );
 
diff --git a/packages/edit-site/src/components/revisions/index.js b/packages/edit-site/src/components/revisions/index.js
@@ -53,7 +53,10 @@ function Revisions( { userConfig, blocks } ) {
 		[]
 	);
 	const settings = useMemo(
-		() => ( { ...originalSettings, __unstableIsPreviewMode: true } ),
+		() => ( {
+			...originalSettings,
+			isPreviewMode: true,
+		} ),
 		[ originalSettings ]
 	);
 
diff --git a/packages/edit-site/src/components/style-book/index.js b/packages/edit-site/src/components/style-book/index.js
@@ -91,7 +91,10 @@ function StyleBook( {
 	);
 
 	const settings = useMemo(
-		() => ( { ...originalSettings, __unstableIsPreviewMode: true } ),
+		() => ( {
+			...originalSettings,
+			isPreviewMode: true,
+		} ),
 		[ originalSettings ]
 	);
 
@@ -328,7 +331,7 @@ const Example = ( { id, title, blocks, isSelected, onClick } ) => {
 		() => ( {
 			...originalSettings,
 			focusMode: false, // Disable "Spotlight mode".
-			__unstableIsPreviewMode: true,
+			isPreviewMode: true,
 		} ),
 		[ originalSettings ]
 	);
diff --git a/packages/editor/src/components/commands/index.js b/packages/editor/src/components/commands/index.js
@@ -57,7 +57,7 @@ function useEditorCommandLoader() {
 			isDistractionFree: get( 'core', 'distractionFree' ),
 			isFocusMode: get( 'core', 'focusMode' ),
 			isTopToolbar: get( 'core', 'fixedToolbar' ),
-			isPreviewMode: getSettings().__unstableIsPreviewMode,
+			isPreviewMode: getSettings().isPreviewMode,
 			isViewable: getPostType( getCurrentPostType() )?.viewable ?? false,
 			isCodeEditingEnabled: getEditorSettings().codeEditingEnabled,
 			isRichEditingEnabled: getEditorSettings().richEditingEnabled,
diff --git a/packages/editor/src/components/editor-interface/index.js b/packages/editor/src/components/editor-interface/index.js
@@ -83,7 +83,7 @@ export default function EditorInterface( {
 			isInserterOpened: select( editorStore ).isInserterOpened(),
 			isListViewOpened: select( editorStore ).isListViewOpened(),
 			isDistractionFree: get( 'core', 'distractionFree' ),
-			isPreviewMode: editorSettings.__unstableIsPreviewMode,
+			isPreviewMode: editorSettings.isPreviewMode,
 			showBlockBreadcrumbs: get( 'core', 'showBlockBreadcrumbs' ),
 			// translators: Default label for the Document in the Block Breadcrumb.
 			documentLabel: postTypeLabel || _x( 'Document', 'noun' ),
diff --git a/packages/editor/src/components/provider/index.js b/packages/editor/src/components/provider/index.js
@@ -330,7 +330,7 @@ export const ExperimentalEditorProvider = withRegistryProvider(
 							useSubRegistry={ false }
 						>
 							{ children }
-							{ ! settings.__unstableIsPreviewMode && (
+							{ ! settings.isPreviewMode && (
 								<>
 									<PatternsMenuItems />
 									<TemplatePartMenuItems />
diff --git a/packages/editor/src/components/provider/use-block-editor-settings.js b/packages/editor/src/components/provider/use-block-editor-settings.js
diff --git a/packages/editor/src/components/visual-editor/index.js b/packages/editor/src/components/visual-editor/index.js
