feat: Expose autocomplete triggers and text insertion utility (#165)

* feat: Observe `@` autocomplete triggers

* feat: Observe `+` autocomplete triggers

* feat: Notify native host on autocomplete trigger

Enable the host to respond to autocomplete events.

* feat: Expose `appendTextAtCursor` bridge method

* fix: Avoid restarting autocompletion after selecting option

Debouncing ensures the native suggestion UI does not reappear after
selecting an suggestion.

* feat: iOS apps receive autocompletion events

* feat: iOS apps append text at cursor

* fix: Ensure hook registration occurs in global `wp.hooks` namespace

Bundling the `@wordpress/hook` package meant two namespaces existed:

1. The module bundled by Vite;
2. And the `wp.hooks` global provided by the remote site scripts.

Hooks registered by GutenbergKit used the former, but the editor runtime
relied upon the latter. Therefore, the GutenbergKit hooks were never
applied. Using a single namespace resolves this issue.

Originally, bundling select modules was done in service of using
`@wordpress/api-fetch` for fetching editor assets from a remote site.
Now that the native bridge authenticates and performs this request, we
no longer need these bundled modules. We can rely upon the globals
provided by the remote site assets.

* feat: Android support for autocompleter events and text insertion

Enable Android apps to:

1. Receive notifications when autocompleters are triggered (@ and +
   symbols)
2. Programmatically insert text at the cursor position in the editor

* fix: Only trigger autocompleter on initial trigger insertion

Avoid triggering autocompleter when modifying string prefixed with
trigger--e.g., deleting an existing string.

Behavior:
- @<cursor> triggers the event (filterValue is empty)
- @query<cursor> does not trigger (filterValue contains "query")
- Same pattern applies to + symbol

This ensures native apps only receive the initial trigger notification,
not continuous events while the user is typing.

* fix: Prevent autocompletion unless white space surrounds prefix trigger

The autocompletion should not disrupt typing strings like an
email--e.g., `[email protected]`.

* fix: Authenticate editor assets request for Android

* docs: Improve documentation

* refactor: Rely upon shorthand property name

* build: Simplify side-effect module externalization

We do not need special handling of side-effect modules. The regex change
ensures they are matched by the Vite plugin. The logic then removes the
side-effect module import entirely. This is appropriate, as the remote
editor assets should already include/load the side-effect modules. E.g.,
the `format-library` side effects are included in remote editor assets.

* fix: Avoid loading duplicate CSS files

By ignoring CSS files within the module import regex, we loaded the CSS
twice: once within the bundle, again from the remote site assets. We now
match CSS imports and remove them as side-effect imports.

Inlined CSS files are treated differently. We bundle these imports so
that the JavaScript can act upon the imported string content.

* refactor: Reduce log noise

* fix: Expand iOS string encoding to avoid stripping content

The previous implementation might lead to data loss by stripping
unsupported characters.

Author: dcalhoun

android/Gutenberg/src/main/java/org/wordpress/gutenberg/GutenbergView.kt

@@ -58,6 +58,7 @@ class GutenbergView : WebView {
     private var openMediaLibraryListener: OpenMediaLibraryListener? = null
     private var editorDidBecomeAvailableListener: EditorAvailableListener? = null
     private var logJsExceptionListener: LogJsExceptionListener? = null
+    private var autocompleterTriggeredListener: AutocompleterTriggeredListener? = null
 
     var textEditorEnabled: Boolean = false
         set(value) {
@@ -88,6 +89,10 @@ class GutenbergView : WebView {
         logJsExceptionListener = listener
     }
 
+    fun setAutocompleterTriggeredListener(listener: AutocompleterTriggeredListener) {
+        autocompleterTriggeredListener = listener
+    }
+
     fun setOnFileChooserRequestedListener(listener: (Intent, Int) -> Unit) {
         onFileChooserRequested = listener
     }
@@ -403,6 +408,10 @@ class GutenbergView : WebView {
         fun onLogJsException(exception: GutenbergJsException)
     }
 
+    interface AutocompleterTriggeredListener {
+        fun onAutocompleterTriggered(type: String)
+    }
+
     fun getTitleAndContent(originalContent: CharSequence, callback: TitleAndContentCallback, completeComposition: Boolean = false) {
         if (!isEditorLoaded) {
             Log.e("GutenbergView", "You can't change the editor content until it has loaded")
@@ -445,6 +454,17 @@ class GutenbergView : WebView {
         }
     }
 
+    fun appendTextAtCursor(text: String) {
+        if (!isEditorLoaded) {
+            Log.e("GutenbergView", "You can't append text until the editor has loaded")
+            return
+        }
+        val encodedText = encodeForEditor(text)
+        handler.post {
+            this.evaluateJavascript("editor.appendTextAtCursor(decodeURIComponent('$encodedText'));", null)
+        }
+    }
+
     @JavascriptInterface
     fun onEditorLoaded() {
         Log.i("GutenbergView", "EditorLoaded received in native code")
@@ -547,6 +567,13 @@ class GutenbergView : WebView {
         Log.i("GutenbergView", "BlockPickerShouldShow")
     }
 
+    @JavascriptInterface
+    fun onAutocompleterTriggered(type: String) {
+        handler.post {
+            autocompleterTriggeredListener?.onAutocompleterTriggered(type)
+        }
+    }
+
     fun resetFilePathCallback() {
         filePathCallback = null
     }
@@ -562,6 +589,7 @@ class GutenbergView : WebView {
         editorDidBecomeAvailable = null
         filePathCallback = null
         onFileChooserRequested = null
+        autocompleterTriggeredListener = null
         handler.removeCallbacksAndMessages(null)
         this.destroy()
     }

ios/Sources/GutenbergKit/Sources/EditorJSMessage.swift

@@ -37,6 +37,8 @@ struct EditorJSMessage {
         case showBlockPicker
         /// User requested the Media Library.
         case openMediaLibrary
+        /// The user triggered an autocompleter.
+        case onAutocompleterTriggered
     }
 
     struct DidUpdateBlocksBody: Decodable {
@@ -51,4 +53,8 @@ struct EditorJSMessage {
     struct DidUpdateFeaturedImageBody: Decodable {
         let mediaID: Int
     }
+
+    struct AutocompleterTriggeredBody: Decodable {
+        let type: String
+    }
 }

ios/Sources/GutenbergKit/Sources/EditorViewController.swift

@@ -297,6 +297,14 @@ public final class EditorViewController: UIViewController, GutenbergEditorContro
         evaluate("editor.setMediaUploadAttachment(\(media));")
     }
 
+    /// Appends text at the current cursor position in the editor.
+    ///
+    /// - parameter text: The text to append at the cursor position.
+    public func appendTextAtCursor(_ text: String) {
+        let escapedText = text.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? text
+        evaluate("editor.appendTextAtCursor(decodeURIComponent('\(escapedText)'));")
+    }
+
     // MARK: - GutenbergEditorControllerDelegate
 
     fileprivate func controller(_ controller: GutenbergEditorController, didReceiveMessage message: EditorJSMessage) {
@@ -326,6 +334,9 @@ public final class EditorViewController: UIViewController, GutenbergEditorContro
             case .openMediaLibrary:
                 let config = try message.decode(OpenMediaLibraryAction.self)
                 openMediaLibrary(config)
+            case .onAutocompleterTriggered:
+                let body = try message.decode(EditorJSMessage.AutocompleterTriggeredBody.self)
+                delegate?.editor(self, didTriggerAutocompleter: body.type)
             }
         } catch {
             fatalError("failed to decode message: \(error)")

ios/Sources/GutenbergKit/Sources/EditorViewControllerDelegate.swift

@@ -34,6 +34,11 @@ public protocol EditorViewControllerDelegate: AnyObject {
     func editor(_ viewController: EditorViewController, didLogException error: GutenbergJSException)
 
     func editor(_ viewController: EditorViewController, didRequestMediaFromSiteMediaLibrary config: OpenMediaLibraryAction)
+
+    /// Notifies the client that an autocompleter was triggered.
+    ///
+    /// - parameter type: The type of autocompleter that was triggered (e.g., "plus-symbol", "at-symbol").
+    func editor(_ viewController: EditorViewController, didTriggerAutocompleter type: String)
 }
 
 public struct EditorState {

src/components/editor/index.jsx

@@ -19,6 +19,8 @@ import { useMediaUpload } from './use-media-upload';
 import TextEditor from '../text-editor';
 import { useSyncFeaturedImage } from './use-sync-featured-image';
 import { useDevModeNotice } from './use-dev-mode-notice';
+import { useAtAutocompleter } from './use-at-autocompleter';
+import { usePlusAutocompleter } from './use-plus-autocompleter';
 
 /**
  * @typedef {import('../utils/bridge').Post} Post
@@ -43,6 +45,8 @@ export default function Editor( { post, children, hideTitle } ) {
 	useEditorSetup( post );
 	useMediaUpload();
 	useDevModeNotice();
+	useAtAutocompleter();
+	usePlusAutocompleter();
 
 	const { isReady, mode, isRichEditingEnabled, currentPost } = useSelect(
 		( select ) => {

src/components/editor/use-at-autocompleter.js

@@ -0,0 +1,67 @@
+/**
+ * WordPress dependencies
+ */
+import { addFilter, removeFilter } from '@wordpress/hooks';
+import { useEffect } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { onAutocompleterTriggered } from '../../utils/bridge';
+
+/**
+ * Adds a filter for the Autocomplete completers to show an alert when @ is typed.
+ *
+ * @return {void}
+ */
+export function useAtAutocompleter() {
+	useEffect( () => {
+		// Avoid conflicts with core's default autocompleter
+		removeFilter(
+			'editor.Autocomplete.completers',
+			'editor/autocompleters/set-default-completers'
+		);
+
+		addFilter(
+			'editor.Autocomplete.completers',
+			'GutenbergKit/at-symbol-alert',
+			addAtSymbolCompleter
+		);
+
+		return () => {
+			removeFilter(
+				'editor.Autocomplete.completers',
+				'GutenbergKit/at-symbol-alert'
+			);
+		};
+	}, [] );
+}
+
+/**
+ * Adds the @ symbol autocompleter to the completers array.
+ *
+ * @param {Array} completers Existing completers.
+ * @return {Array} Updated completers array.
+ */
+function addAtSymbolCompleter( completers = [] ) {
+	const atSymbolCompleter = {
+		name: 'at-symbol',
+		triggerPrefix: '@',
+		options: ( filterValue ) => {
+			// Only trigger when cursor is directly after @ (no characters typed yet)
+			if ( filterValue === '' ) {
+				onAutocompleterTriggered( 'at-symbol' );
+			}
+			// Return empty array since we're not providing actual completion options
+			return [];
+		},
+		allowContext: ( before, after ) => {
+			const beforeEmptyOrWhitespace = /^$|\s$/.test( before );
+			const afterEmptyOrWhitespace = /^$|^\s/.test( after );
+			return beforeEmptyOrWhitespace && afterEmptyOrWhitespace;
+		},
+		isDebounced: true,
+	};
+
+	return [ ...completers, atSymbolCompleter ];
+}

src/components/editor/use-host-bridge.js

@@ -5,7 +5,14 @@ import { useEffect, useCallback, useRef } from '@wordpress/element';
 import { useDispatch, useSelect } from '@wordpress/data';
 import { store as coreStore } from '@wordpress/core-data';
 import { store as editorStore } from '@wordpress/editor';
-import { parse, serialize } from '@wordpress/blocks';
+import { parse, serialize, getBlockType } from '@wordpress/blocks';
+import { store as blockEditorStore } from '@wordpress/block-editor';
+import { insert, create, toHTMLString } from '@wordpress/rich-text';
+
+/**
+ * Internal dependencies
+ */
+import { warn } from '../../utils/logger';
 
 window.editor = window.editor || {};
 
@@ -14,6 +21,13 @@ export function useHostBridge( post, editorRef ) {
 	const { undo, redo, switchEditorMode } = useDispatch( editorStore );
 	const { getEditedPostAttribute, getEditedPostContent } =
 		useSelect( editorStore );
+	const { updateBlock, selectionChange } = useDispatch( blockEditorStore );
+	const {
+		getSelectedBlockClientId,
+		getBlock,
+		getSelectionStart,
+		getSelectionEnd,
+	} = useSelect( blockEditorStore );
 
 	const editContent = useCallback(
 		( edits ) => {
@@ -79,6 +93,64 @@ export function useHostBridge( post, editorRef ) {
 			switchEditorMode( mode );
 		};
 
+		window.editor.appendTextAtCursor = ( text ) => {
+			const selectedBlockClientId = getSelectedBlockClientId();
+
+			if ( ! selectedBlockClientId ) {
+				warn( 'Unable to append text: no block selected' );
+				return false;
+			}
+
+			const block = getBlock( selectedBlockClientId );
+
+			if ( ! block ) {
+				warn(
+					'Unable to append text: could not retrieve selected block'
+				);
+				return false;
+			}
+
+			const blockType = getBlockType( block.name );
+			const hasContentAttribute = blockType?.attributes?.content;
+
+			if ( ! hasContentAttribute ) {
+				warn(
+					`Unable to append text: block type ${ block.name } does not support text content`
+				);
+				return false;
+			}
+
+			const blockContent = block.attributes?.content || '';
+			const currentValue = create( { html: blockContent } );
+			const selectionStart = getSelectionStart();
+			const selectionEnd = getSelectionEnd();
+			const newValue = insert(
+				currentValue,
+				text,
+				selectionStart?.offset,
+				selectionEnd?.offset
+			);
+
+			updateBlock( selectedBlockClientId, {
+				attributes: {
+					...block.attributes,
+					content: toHTMLString( { value: newValue } ),
+				},
+			} );
+
+			const newCursorPosition =
+				selectionStart?.offset + text.length || newValue.text.length;
+
+			selectionChange( {
+				clientId: selectionStart?.clientId || selectedBlockClientId,
+				attributeKey: selectionStart?.attributeKey || 'content',
+				startOffset: newCursorPosition,
+				endOffset: newCursorPosition,
+			} );
+
+			return true;
+		};
+
 		return () => {
 			delete window.editor.setContent;
 			delete window.editor.setTitle;
@@ -87,6 +159,7 @@ export function useHostBridge( post, editorRef ) {
 			delete window.editor.undo;
 			delete window.editor.redo;
 			delete window.editor.switchEditorMode;
+			delete window.editor.appendTextAtCursor;
 		};
 	}, [
 		editorRef,
@@ -96,6 +169,12 @@ export function useHostBridge( post, editorRef ) {
 		redo,
 		switchEditorMode,
 		undo,
+		getSelectedBlockClientId,
+		getBlock,
+		getSelectionStart,
+		getSelectionEnd,
+		updateBlock,
+		selectionChange,
 	] );
 }
 

src/components/editor/use-plus-autocompleter.js

@@ -0,0 +1,61 @@
+/**
+ * WordPress dependencies
+ */
+import { addFilter, removeFilter } from '@wordpress/hooks';
+import { useEffect } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { onAutocompleterTriggered } from '../../utils/bridge';
+
+/**
+ * Adds a filter for the Autocomplete completers to show an alert when + is typed.
+ *
+ * @return {void}
+ */
+export function usePlusAutocompleter() {
+	useEffect( () => {
+		addFilter(
+			'editor.Autocomplete.completers',
+			'GutenbergKit/plus-symbol-alert',
+			addPlusSymbolCompleter
+		);
+
+		return () => {
+			removeFilter(
+				'editor.Autocomplete.completers',
+				'GutenbergKit/plus-symbol-alert'
+			);
+		};
+	}, [] );
+}
+
+/**
+ * Adds the + symbol autocompleter to the completers array.
+ *
+ * @param {Array} completers Existing completers.
+ * @return {Array} Updated completers array.
+ */
+function addPlusSymbolCompleter( completers = [] ) {
+	const plusSymbolCompleter = {
+		name: 'plus-symbol',
+		triggerPrefix: '+',
+		options: ( filterValue ) => {
+			// Only trigger when cursor is directly after + (no characters typed yet)
+			if ( filterValue === '' ) {
+				onAutocompleterTriggered( 'plus-symbol' );
+			}
+			// Return empty array since we're not providing actual completion options
+			return [];
+		},
+		allowContext: ( before, after ) => {
+			const beforeEmptyOrWhitespace = /^$|\s$/.test( before );
+			const afterEmptyOrWhitespace = /^$|^\s/.test( after );
+			return beforeEmptyOrWhitespace && afterEmptyOrWhitespace;
+		},
+		isDebounced: true,
+	};
+
+	return [ ...completers, plusSymbolCompleter ];
+}