Enhance activeFormats handling in rich text components

- Updated the annotation handling to preserve user-defined formats when applying annotations programmatically.
- Modified the `addInvisibleFormats` function to pass the full value object, allowing better management of active formats.
- Improved the `getActiveFormats` function to clone formats only when necessary, optimizing performance.
- Adjusted event listeners to filter out editor-only formats (like annotations) from active formats during typing and selection changes.

These changes ensure that user formats are maintained correctly while managing annotations, enhancing the overall editing experience.

Refs #71698

Author: maxschmeling

packages/annotations/src/format/annotation.js

@@ -156,13 +156,28 @@ export const annotation = {
 		};
 	},
 	__experimentalCreatePrepareEditableTree( { annotations } ) {
-		return ( formats, text ) => {
+		return ( formats, text, value ) => {
 			if ( annotations.length === 0 ) {
 				return formats;
 			}
 
 			let record = { formats, text };
+			// Preserve activeFormats when applying annotations so user formats
+			// (like bold) are not lost when annotations are added programmatically.
+			const originalActiveFormats = value?.activeFormats
+				? value.activeFormats.filter(
+						( format ) => format.type !== FORMAT_NAME
+				  )
+				: undefined;
+			if ( originalActiveFormats ) {
+				record.activeFormats = originalActiveFormats;
+			}
 			record = applyAnnotations( record, annotations );
+			// Restore original activeFormats after applying annotations, since
+			// annotations are editor-only formats and shouldn't be in activeFormats.
+			if ( originalActiveFormats ) {
+				record.activeFormats = originalActiveFormats;
+			}
 			return record.formats;
 		};
 	},

packages/block-editor/src/components/rich-text/index.js

@@ -376,7 +376,7 @@ export function RichTextWrapper(
 
 	function addInvisibleFormats( value ) {
 		return prepareHandlers.reduce(
-			( accumulator, fn ) => fn( accumulator, value.text ),
+			( accumulator, fn ) => fn( accumulator, value.text, value ),
 			value.formats
 		);
 	}

packages/rich-text/src/component/event-listeners/format-boundaries.js

@@ -7,6 +7,7 @@ import { LEFT, RIGHT } from '@wordpress/keycodes';
  * Internal dependencies
  */
 import { isCollapsed } from '../../is-collapsed';
+import { isFormatEqual } from '../../is-format-equal';
 
 const EMPTY_ACTIVE_FORMATS = [];
 
@@ -65,28 +66,75 @@ export default ( props ) => ( element ) => {
 		const formatsBefore = formats[ start - 1 ] || EMPTY_ACTIVE_FORMATS;
 		const formatsAfter = formats[ start ] || EMPTY_ACTIVE_FORMATS;
 		const destination = isReverse ? formatsBefore : formatsAfter;
-		const isIncreasing = currentActiveFormats.every(
-			( format, index ) => format === destination[ index ]
+
+		// Split formats into User formats (bold, italic, etc) and Annotations.
+		// We treat Annotations as a "layer" on top of User formats.
+		const isAnnotation = ( format ) => format.type === 'core/annotation';
+		const currentAnnotations = currentActiveFormats.filter( isAnnotation );
+		const currentUserFormats = currentActiveFormats.filter(
+			( format ) => ! isAnnotation( format )
+		);
+		const destAnnotations = destination.filter( isAnnotation );
+		const destUserFormats = destination.filter(
+			( format ) => ! isAnnotation( format )
 		);
 
-		let newActiveFormatsLength = currentActiveFormats.length;
+		// Check if User formats match the destination
+		const userFormatsMatch =
+			currentUserFormats.length === destUserFormats.length &&
+			currentUserFormats.every( ( format, index ) =>
+				isFormatEqual( format, destUserFormats[ index ] )
+			);
 
-		if ( ! isIncreasing ) {
-			newActiveFormatsLength--;
-		} else if ( newActiveFormatsLength < destination.length ) {
-			newActiveFormatsLength++;
-		}
+		// Check if Annotations match the destination
+		const annotationsMatch =
+			currentAnnotations.length === destAnnotations.length &&
+			currentAnnotations.every( ( format, index ) =>
+				isFormatEqual( format, destAnnotations[ index ] )
+			);
 
-		if ( newActiveFormatsLength === currentActiveFormats.length ) {
-			record.current._newActiveFormats = destination;
+		// console.log( 'Boundaries Debug:', {
+		// 	direction: isReverse ? 'left' : 'right',
+		// 	currentActive: currentActiveFormats.map( f => f.type ),
+		// 	destination: destination.map( f => f.type ),
+		// 	userMatch: userFormatsMatch,
+		// 	annMatch: annotationsMatch
+		// } );
+
+		if ( userFormatsMatch && annotationsMatch ) {
 			return;
 		}
 
 		event.preventDefault();
 
-		const origin = isReverse ? formatsAfter : formatsBefore;
-		const source = isIncreasing ? destination : origin;
-		const newActiveFormats = source.slice( 0, newActiveFormatsLength );
+		let newActiveFormats;
+
+		// Logic: Annotations are on top. If User formats need to change, we must
+		// strip the Annotation layer first.
+		if ( ! userFormatsMatch && currentAnnotations.length > 0 ) {
+			newActiveFormats = currentUserFormats;
+		} else if ( ! userFormatsMatch ) {
+			// Transition User formats using standard stack logic
+			const isIncreasing = currentUserFormats.every( ( format, index ) =>
+				isFormatEqual( format, destUserFormats[ index ] )
+			);
+			let newLength = currentUserFormats.length;
+
+			if ( ! isIncreasing ) {
+				newLength--;
+			} else if ( newLength < destUserFormats.length ) {
+				newLength++;
+			}
+
+			const source = isIncreasing ? destUserFormats : currentUserFormats;
+			newActiveFormats = source.slice( 0, newLength );
+		} else {
+			// User formats match, but Annotations don't.
+			// Transition Annotations (Add or Remove based on destination).
+			// We always stack Annotations at the end.
+			newActiveFormats = [ ...currentUserFormats, ...destAnnotations ];
+		}
+
 		const newValue = {
 			...record.current,
 			activeFormats: newActiveFormats,

packages/rich-text/src/component/event-listeners/input-and-selection.js

@@ -88,12 +88,18 @@ export default ( props ) => ( element ) => {
 		const currentValue = createRecord();
 		const { start, activeFormats: oldActiveFormats = [] } = record.current;
 
+		// Filter out editor-only formats (like annotations) from activeFormats,
+		// since they shouldn't be applied when typing.
+		const filteredActiveFormats = oldActiveFormats.filter(
+			( format ) => format.type !== 'core/annotation'
+		);
+
 		// Update the formats between the last and new caret position.
 		const change = updateFormats( {
 			value: currentValue,
 			start,
 			end: currentValue.start,
-			formats: oldActiveFormats,
+			formats: filteredActiveFormats,
 		} );
 
 		handleChange( change );
@@ -169,6 +175,7 @@ export default ( props ) => ( element ) => {
 		);
 
 		// Update the value with the new active formats.
+		// getActiveFormats already filters out editor-only formats like annotations.
 		newValue.activeFormats = newActiveFormats;
 
 		// It is important that the internal value is updated first,

packages/rich-text/src/component/index.js

@@ -153,6 +153,8 @@ export function useRichText( {
 	function applyFromProps() {
 		// Get previous value before updating
 		const previousValue = _valueRef.current;
+		// Preserve activeFormats from current record before updating
+		const preservedActiveFormats = recordRef.current?.activeFormats;
 
 		setRecordFromProps();
 
@@ -168,6 +170,20 @@ export function useRichText( {
 			ref.current.ownerDocument.activeElement
 		);
 
+		// Preserve activeFormats when only formats changed (e.g., annotations added),
+		// not when content length changed or element doesn't have focus.
+		if (
+			preservedActiveFormats &&
+			! contentLengthChanged &&
+			hasFocus &&
+			recordRef.current.start === recordRef.current.end
+		) {
+			recordRef.current = {
+				...recordRef.current,
+				activeFormats: preservedActiveFormats,
+			};
+		}
+
 		// Skip re-applying the selection state when content changed from external source
 		// (e.g., typing in sidebar input changes canvas text)
 		const skipSelection = contentLengthChanged && ! hasFocus;

packages/rich-text/src/get-active-formats.js

@@ -47,9 +47,8 @@ export function getActiveFormats( value, EMPTY_ACTIVE_FORMATS = [] ) {
 
 	const selectedFormats = formats.slice( start, end );
 
-	// Clone the formats so we're not mutating the live value.
-	const _activeFormats = [ ...selectedFormats[ 0 ] ];
 	let i = selectedFormats.length;
+	let _activeFormats;
 
 	// For performance reasons, start from the end where it's much quicker to
 	// realise that there are no active formats.
@@ -62,6 +61,11 @@ export function getActiveFormats( value, EMPTY_ACTIVE_FORMATS = [] ) {
 			return EMPTY_ACTIVE_FORMATS;
 		}
 
+		// Clone the formats so we're not mutating the live value.
+		// Assign only when we know we'll use it (after early return check).
+		if ( _activeFormats === undefined ) {
+			_activeFormats = selectedFormats[ 0 ] || [];
+		}
 		let ii = _activeFormats.length;
 
 		// Loop over the active formats and remove any that are not present at