refactor: Organize editor setup (#242)

* refactor: Relocate jQuery global assignment to environment setup

Relates to environment setup.

* docs: Update outdated CLAUDE.md Make target reference

* refactor: Editor setup prefers async/await over Promises

Improve readability.

* refactor: Rename WordPress globals function

* refactor: Update locale comment

Use consistent terms between functions and comments.

* refactor: Extract body class utility

Simplify `setUpEditorEnvironment` logic to improve readability.

* refactor: Organize imports to follow Gutenberg project practices

* refactor: Expose jQuery alongside other WordPress globals

* refactor: Avoid import side effects

* refactor: Update imports to follow Gutenberg project practices

* refactor: Document editor environment functions

* refactor: Remove unnecessary localization lazy loading

This modules does not reference `window.wp` globals other than those
loaded by the `wordpress-i18n` module via the script tag in the entry
`index.html` file.

* refactor: Wrap all editor set up logic within try-catch

* refactor: Reduce repetition in `setBodyClasses` utility

* refactor: Extract platform detection logic

Reduce duplication.

* refactor: Remove unused return value

This utility is solely used to await the availability of the bridge
configuration. The value itself is retrieved via `getGBKit()`.

* refactor: Rename functions for consistency

* refactor: Node.js ESM module import include file ending

Node.js ESM stictly follows the ECMAScript spec, which requires module
file endings. Vite, however, is more forgiving. We could consider
updating all project imports for consistency.

* refactor: Relocate error load notice to directory

Align with all other component organization.

* refactor: Align native inserter name with core inserter

* refactor: Correct editor load notice description

* refactor: Remove unused export

* refactor: Simplify body class utility

* refactor: Reuse default locale constant

Author: dcalhoun

CLAUDE.md

@@ -67,7 +67,7 @@ make lint-fix-js
 npm run lint:js:fix
 
 # Format JavaScript code
-make format-js
+make format
 # or
 npm run format
 ```
@@ -193,5 +193,5 @@ Always run these commands before committing:
 make lint-js
 
 # Format JavaScript code
-make format-js
+make format
 ```

src/components/editor-load-notice.jsx renamed to src/components/editor-load-notice/index.jsx

@@ -11,7 +11,7 @@ const pluginLoadFailedNotice = __(
 );
 
 /**
- * Displays a notice with actions to retry or dismiss.
+ * Displays a notice regarding the plugin loading outcome.
  *
  * @param {Object}  props                  Component props.
  * @param {string}  props.className        Additional class names to apply.

src/components/editor-load-notice.test.jsx renamed to src/components/editor-load-notice/index.test.jsx

@@ -7,7 +7,7 @@ import { render, screen, fireEvent, act } from '@testing-library/react';
 /**
  * Internal dependencies
  */
-import EditorLoadNotice from './editor-load-notice';
+import EditorLoadNotice from '.';
 
 vi.mock( '@wordpress/i18n' );
 vi.mock( '@wordpress/components' );

src/components/editor-toolbar/index.jsx

@@ -28,7 +28,7 @@ import './style.scss';
 import { useModalize } from './use-modalize';
 import { useModalDialogState } from '../editor/use-modal-dialog-state';
 import { getGBKit } from '../../utils/bridge';
-import NativeBlockInserterButton from '../native-block-inserter-button';
+import NativeInserter from '../native-inserter';
 import { useScrollIndicators } from './use-scroll-indicators';
 
 /**
@@ -98,7 +98,7 @@ const EditorToolbar = ( { className } ) => {
 	);
 
 	const addBlockButton = enableNativeBlockInserter ? (
-		<NativeBlockInserterButton
+		<NativeInserter
 			open={ isInserterOpened }
 			onToggle={ setIsInserterOpened }
 		/>

src/components/native-block-inserter-button/index.jsx renamed to src/components/native-inserter/index.jsx

@@ -1,13 +1,7 @@
-/**
- * External dependencies
- */
-import jquery from 'jquery';
-
 /**
  * Internal dependencies
  */
 import { setUpEditorEnvironment } from './utils/editor-environment';
 import './index.scss';
 
-window.jQuery = jquery; // Expose jQuery for plugins
 setUpEditorEnvironment();

src/index.js

@@ -18,7 +18,7 @@ import { getGBKit } from './bridge';
  *
  * @return {void}
  */
-export function initializeApiFetch() {
+export function configureApiFetch() {
 	const { siteApiRoot = '' } = getGBKit();
 
 	apiFetch.use( apiFetch.createRootURLMiddleware( siteApiRoot ) );

src/utils/api-fetch.js

@@ -19,7 +19,7 @@ import apiFetch from '@wordpress/api-fetch';
 /**
  * Internal dependencies
  */
-import { initializeApiFetch } from './api-fetch';
+import { configureApiFetch } from './api-fetch';
 import * as bridge from './bridge';
 
 vi.mock( './bridge' );
@@ -34,7 +34,7 @@ describe( 'api-fetch credentials handling', () => {
 		} );
 
 		// Initialize middleware once - it will persist across all tests
-		initializeApiFetch();
+		configureApiFetch();
 	} );
 
 	beforeEach( () => {

src/utils/api-fetch.test.js

@@ -288,33 +288,23 @@ export function logException(
  *
  * @param {number} timeoutMs Timeout in milliseconds after which to reject.
  *
- * @return {Promise<GBKitConfig>} Promise that resolves with GBKit config or rejects after timeout.
+ * @return {Promise<void>} Promise that resolves with GBKit config or rejects after timeout.
  */
 export function awaitGBKitGlobal( timeoutMs = 3000 ) {
 	return new Promise( ( resolve, reject ) => {
 		const startTime = Date.now();
 
 		const checkGBKit = () => {
 			if ( window.GBKit ) {
-				resolve( window.GBKit );
+				resolve();
 				return;
 			}
 
 			if ( Date.now() - startTime >= timeoutMs ) {
-				// In development mode, bypass the GBKit requirement and seed a default post,
-				// allowing the editor to load without the native bridge to simplify testing.
+				// In development mode, bypass the GBKit requirement allowing the editor
+				// to load without the native bridge to simplify testing.
 				if ( isDevMode() ) {
-					resolve( {
-						post: {
-							id: -1,
-							type: 'post',
-							title: '',
-							content: '',
-							status: 'auto-draft',
-						},
-						themeStyles: false,
-						hideTitle: false,
-					} );
+					resolve();
 					return;
 				}
 

src/utils/bridge.js

@@ -2,11 +2,13 @@
  * Internal dependencies
  */
 import { awaitGBKitGlobal, editorLoaded, getGBKit } from './bridge';
+import { configureLocale } from './localization';
 import { loadEditorAssets } from './editor-loader';
 import { initializeVideoPressAjaxBridge } from './videopress-bridge';
 import EditorLoadError from '../components/editor-load-error';
 import { error } from './logger';
 import { setUpGlobalErrorHandlers } from './global-error-handler';
+import { Platform } from './platform';
 import './editor-styles';
 
 /**
@@ -15,82 +17,115 @@ import './editor-styles';
  *
  * @return {Promise} Promise that resolves when initialization is complete
  */
-export function setUpEditorEnvironment() {
-	setUpGlobalErrorHandlers();
+export async function setUpEditorEnvironment() {
+	try {
+		setUpGlobalErrorHandlers();
+		setBodyClasses();
+		await awaitGBKitGlobal();
+		await configureLocale();
+		await initializeWordPressGlobals();
+		await configureApiFetch();
+		initializeVideoPressAjaxBridge();
+		const pluginLoadResult = await loadPluginsIfEnabled();
+		await initializeEditor( pluginLoadResult );
+	} catch ( err ) {
+		handleError( err );
+	}
+}
 
-	// Detect platform and add class to body for platform-specific styling
-	if ( typeof window !== 'undefined' && window.webkit ) {
-		document.body.classList.add( 'is-ios' );
-	} else if ( typeof window !== 'undefined' && window.editorDelegate ) {
-		document.body.classList.add( 'is-android' );
+/**
+ * Adds conditional CSS classes to `document.body`.
+ *
+ * @return {void}
+ */
+function setBodyClasses() {
+	if ( typeof window === 'undefined' ) {
+		return;
 	}
 
-	// Rely upon promises rather than async/await to avoid timeouts caused by
-	// circular dependencies. Addressing the circular dependencies is quite
-	// challenging due to Vite's preload helpers and bugs in `manualChunks`
-	// configuration.
-	//
-	// See:
-	// - https://github.com/vitejs/vite/issues/18551
-	// - https://github.com/vitejs/vite/issues/13952
-	// - https://github.com/vitejs/vite/issues/5189#issuecomment-2175410148
-	return awaitGBKitGlobal()
-		.then( configureLocale )
-		.then( loadRemainingGlobals )
-		.then( initializeApiFetchWrapper )
-		.then( initializeVideoPressAjaxBridge )
-		.then( loadPluginsIfEnabled )
-		.then( initializeEditor )
-		.catch( handleError );
-}
+	const classNames = [];
 
-function configureLocale() {
-	return import( './localization' ).then(
-		( { configureLocale: _configureLocale } ) => _configureLocale()
-	);
+	if ( Platform.isIOS ) {
+		classNames.push( 'is-ios' );
+	} else if ( Platform.isAndroid ) {
+		classNames.push( 'is-android' );
+	}
+
+	window.document.body.classList.add( ...classNames );
 }
 
-function loadRemainingGlobals() {
-	// Load remaining WordPress globals after i18n is configured.
-	return import( './wordpress-globals' );
+/**
+ * Initialize WordPress global modules. Lazy-loaded to ensure the locale is
+ * configured before importing these modules and referencing the corresponding
+ * `window.wp` globals.
+ *
+ * @return {Promise} Promise that resolves when WordPress globals are initialized
+ */
+async function initializeWordPressGlobals() {
+	const { initializeWordPressGlobals: _initializeWordPressGlobals } =
+		await import( './wordpress-globals' );
+	_initializeWordPressGlobals();
 }
 
-function initializeApiFetchWrapper() {
-	// Load api-fetch now that WordPress globals are available.
-	return import( './api-fetch' ).then(
-		( { initializeApiFetch: _initializeApiFetch } ) => {
-			_initializeApiFetch();
-		}
+/**
+ * Configure `api-fetch` middleware and settings. Lazy-loaded to ensure
+ * WordPress globals are available before importing `api-fetch` and
+ * referencing `window.wp.apiFetch`.
+ */
+async function configureApiFetch() {
+	const { configureApiFetch: _configureApiFetch } = await import(
+		'./api-fetch'
 	);
+	_configureApiFetch();
 }
 
-function loadPluginsIfEnabled() {
+/**
+ * @typedef {Object} PluginLoadResult
+ *
+ * @property {string[] | undefined} [allowedBlockTypes] Array of allowed block types provided by the API.
+ * @property {boolean}              [pluginLoadFailed]  Indicates if plugin loading failed.
+ */
+
+/**
+ * Load plugins if enabled in GBKit settings.
+ *
+ * @return {Promise<PluginLoadResult>} Promise resolving to plugin load results
+ */
+async function loadPluginsIfEnabled() {
 	const { plugins } = getGBKit();
 
 	if ( plugins ) {
-		return loadEditorAssets()
-			.then( ( { allowedBlockTypes } ) => {
-				return { allowedBlockTypes };
-			} )
-			.catch( () => {
-				return Promise.resolve( { pluginLoadFailed: true } );
-			} );
+		try {
+			const { allowedBlockTypes } = await loadEditorAssets();
+			return { allowedBlockTypes, pluginLoadFailed: false };
+		} catch {
+			return { pluginLoadFailed: true };
+		}
 	}
 
-	return Promise.resolve( {} );
+	return { pluginLoadFailed: false };
 }
 
-function initializeEditor( pluginLoadResult = {} ) {
-	return import( './editor' ).then(
-		( { initializeEditor: _initializeEditor } ) => {
-			_initializeEditor( {
-				allowedBlockTypes: pluginLoadResult?.allowedBlockTypes,
-				pluginLoadFailed: pluginLoadResult?.pluginLoadFailed,
-			} );
-		}
-	);
+/**
+ * Initialize the editor module. Lazy-loaded to ensure WordPress globals are
+ * before importing the editor module and referencing `window.wp` globals.
+ *
+ * @param {Object} pluginLoadResult - Results from plugin loading
+ * @return {Promise} Promise that resolves when the editor is initialized
+ */
+async function initializeEditor( pluginLoadResult = {} ) {
+	const { initializeEditor: _initializeEditor } = await import( './editor' );
+	_initializeEditor( {
+		allowedBlockTypes: pluginLoadResult.allowedBlockTypes,
+		pluginLoadFailed: pluginLoadResult.pluginLoadFailed,
+	} );
 }
 
+/**
+ * Log and display an editor load error message.
+ *
+ * @param {Error} err - The error that occurred
+ */
 function handleError( err ) {
 	error( 'Error initializing editor', err );
 	const errorDetails = EditorLoadError( { error: err } );