feat: Expose autocomplete triggers and text insertion utility

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 ];
+}