@wordpress/editor 14.41.1-next.v.202603102151.0 → 14.42.0

package/src/components/collaborators-overlay/overlay.tsx

@@ -1,16 +1,23 @@
-// @ts-expect-error No exported types
-import { useStyleOverride } from '@wordpress/block-editor';
 import { useResizeObserver, useMergeRefs } from '@wordpress/compose';
 import { useCallback, useEffect, useState } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
 
 import Avatar from '../collaborators-presence/avatar';
 import { AVATAR_IFRAME_STYLES } from './avatar-iframe-styles';
 import { OVERLAY_IFRAME_STYLES } from './overlay-iframe-styles';
+import { setDelayedInterval } from './timing-utils';
 import { useBlockHighlighting } from './use-block-highlighting';
 import { useRenderCursors } from './use-render-cursors';
 
+// Milliseconds to wait after a change before recomputing cursor positions.
 const RERENDER_DELAY_MS = 500;
 
+// Periodically recompute cursor positions to account for DOM layout
+// changes that don't trigger awareness state updates (e.g. a collaborator
+// applying formatting shifts text but the cursor's logical position is
+// unchanged). Only active when remote cursors are visible.
+const CURSOR_REDRAW_INTERVAL_MS = 10_000;
+
 interface OverlayProps {
 	blockEditorDocument?: Document;
 	postId: number | null;
@@ -31,11 +38,6 @@ export function Overlay( {
 	postId,
 	postType,
 }: OverlayProps ) {
-	useStyleOverride( {
-		id: 'collaborators-overlay',
-		css: AVATAR_IFRAME_STYLES + OVERLAY_IFRAME_STYLES,
-	} );
-
 	// Use state for the overlay element so that the hook re-runs once the ref is attached.
 	const [ overlayElement, setOverlayElement ] =
 		useState< HTMLDivElement | null >( null );
@@ -74,6 +76,17 @@ export function Overlay( {
 		};
 	}, [ rerenderCursorsAfterDelay, rerenderHighlightsAfterDelay ] );
 
+	useEffect( () => {
+		if ( cursors.length === 0 ) {
+			return;
+		}
+
+		return setDelayedInterval(
+			rerenderCursorsAfterDelay,
+			CURSOR_REDRAW_INTERVAL_MS
+		);
+	}, [ cursors.length, rerenderCursorsAfterDelay ] );
+
 	// Merge the refs to use the same element for both overlay and resize observation
 	const mergedRef = useMergeRefs< HTMLDivElement | null >( [
 		setOverlayElement,
@@ -84,30 +97,49 @@ export function Overlay( {
 	// scrollable elements like cursor indicators.
 	return (
 		<div className="collaborators-overlay-full" ref={ mergedRef }>
+			<style>{ AVATAR_IFRAME_STYLES + OVERLAY_IFRAME_STYLES }</style>
 			{ cursors.map( ( cursor ) => (
-				<div
-					key={ cursor.clientId }
-					className="collaborators-overlay-user"
-					style={ {
-						left: `${ cursor.x }px`,
-						top: `${ cursor.y }px`,
-					} }
-				>
+				<div key={ cursor.clientId }>
+					{ ! cursor.isMe &&
+						cursor.selectionRects?.map( ( rect, index ) => (
+							<div
+								key={ `${ cursor.clientId }-sel-${ index }` }
+								className="collaborators-overlay-selection-rect"
+								style={ {
+									left: `${ rect.x }px`,
+									top: `${ rect.y }px`,
+									width: `${ rect.width }px`,
+									height: `${ rect.height }px`,
+									backgroundColor: cursor.color,
+								} }
+							/>
+						) ) }
 					<div
-						className="collaborators-overlay-user-cursor"
+						className="collaborators-overlay-user"
 						style={ {
-							backgroundColor: cursor.color,
-							height: `${ cursor.height }px`,
+							left: `${ cursor.x }px`,
+							top: `${ cursor.y }px`,
 						} }
-					/>
-					<Avatar
-						className="collaborators-overlay-user-label"
-						variant="badge"
-						size="small"
-						src={ cursor.avatarUrl }
-						name={ cursor.userName }
-						borderColor={ cursor.color }
-					/>
+					>
+						{ ! cursor.isMe && (
+							<div
+								className="collaborators-overlay-user-cursor"
+								style={ {
+									backgroundColor: cursor.color,
+									height: `${ cursor.height }px`,
+								} }
+							/>
+						) }
+						<Avatar
+							className="collaborators-overlay-user-label"
+							variant="badge"
+							size="small"
+							src={ cursor.avatarUrl }
+							name={ cursor.userName }
+							label={ cursor.isMe ? __( 'You' ) : undefined }
+							borderColor={ cursor.color }
+						/>
+					</div>
 				</div>
 			) ) }
 			{ highlights.map( ( highlight ) => (

package/src/components/collaborators-overlay/timing-utils.ts

@@ -0,0 +1,30 @@
+/**
+ * Like setInterval but chains setTimeout calls, so the delay is measured from
+ * the end of one run to the start of the next. This prevents callbacks from
+ * stacking up when the main thread is busy.
+ *
+ * @param callback The function to call repeatedly.
+ * @param delayMs  Milliseconds between runs.
+ * @return A cleanup function that stops the timer.
+ */
+export function setDelayedInterval( callback: () => void, delayMs: number ) {
+	let timerHandle: ReturnType< typeof setTimeout > | null = null;
+
+	const runner = () => {
+		try {
+			callback();
+		} catch ( error ) {
+			// Do nothing
+		}
+
+		timerHandle = setTimeout( runner, delayMs );
+	};
+
+	timerHandle = setTimeout( runner, delayMs );
+
+	return () => {
+		if ( timerHandle ) {
+			clearTimeout( timerHandle );
+		}
+	};
+}

package/src/components/collaborators-overlay/use-block-highlighting.ts

@@ -4,7 +4,7 @@
 import {
 	privateApis as coreDataPrivateApis,
 	SelectionType,
-	type PostEditorAwarenessState,
+	type PostEditorAwarenessState as ActiveCollaborator,
 } from '@wordpress/core-data';
 import { useEffect, useRef, useState } from '@wordpress/element';
 
@@ -50,7 +50,7 @@ export function useBlockHighlighting(
 	rerenderHighlightsAfterDelay: () => () => void;
 } {
 	const highlightedBlockIds = useRef< Set< string > >( new Set() );
-	const userStates: PostEditorAwarenessState[] = useActiveCollaborators(
+	const userStates: ActiveCollaborator[] = useActiveCollaborators(
 		postId ?? null,
 		postType ?? null
 	);
@@ -82,12 +82,13 @@ export function useBlockHighlighting(
 		// same block, only the first one gets the highlight and avatar label.
 		const seen = new Set< string >();
 		const blocksToHighlight = userStates
-			.filter(
-				( userState ) =>
-					! userState.isMe &&
+			.filter( ( userState: ActiveCollaborator ) => {
+				const isWholeBlockSelected =
 					userState.editorState?.selection?.type ===
-						SelectionType.WholeBlock
-			)
+					SelectionType.WholeBlock;
+
+				return ! userState.isMe && isWholeBlockSelected;
+			} )
 			.map( ( userState ) => {
 				let localClientId;
 				try {
@@ -104,9 +105,9 @@ export function useBlockHighlighting(
 
 				return {
 					blockId: localClientId,
-					color: getAvatarBorderColor(
-						userState.collaboratorInfo.id
-					),
+					color: userState.isMe
+						? 'var(--wp-admin-theme-color)'
+						: getAvatarBorderColor( userState.collaboratorInfo.id ),
 					userName: userState.collaboratorInfo.name,
 					avatarUrl: getAvatarUrl(
 						userState.collaboratorInfo.avatar_urls

package/src/components/collaborators-overlay/use-render-cursors.ts

@@ -1,17 +1,25 @@
 import {
 	privateApis as coreDataPrivateApis,
 	SelectionType,
+	type PostEditorAwarenessState as ActiveCollaborator,
 } from '@wordpress/core-data';
+import { useSelect } from '@wordpress/data';
 import { useEffect, useState } from '@wordpress/element';
+import { store as preferencesStore } from '@wordpress/preferences';
+import type { ResolvedSelection } from '@wordpress/core-data';
 
 import { unlock } from '../../lock-unlock';
 import { getAvatarUrl } from './get-avatar-url';
 import { getAvatarBorderColor } from '../collab-sidebar/utils';
+import { computeSelectionVisual } from './compute-selection';
 import { useDebouncedRecompute } from './use-debounced-recompute';
+import type { SelectionRect } from './cursor-dom-utils';
 
 const { useActiveCollaborators, useResolvedSelection } =
 	unlock( coreDataPrivateApis );
 
+export type { SelectionRect };
+
 export interface CursorData {
 	userName: string;
 	clientId: number;
@@ -20,6 +28,8 @@ export interface CursorData {
 	x: number;
 	y: number;
 	height: number;
+	isMe?: boolean;
+	selectionRects?: SelectionRect[];
 }
 
 /**
@@ -48,6 +58,12 @@ export function useRenderCursors(
 		postType ?? null
 	);
 
+	const showOwnCursor = useSelect(
+		( select ) =>
+			select( preferencesStore ).get( 'core', 'showCollaborationCursor' ),
+		[]
+	);
+
 	const [ cursorPositions, setCursorPositions ] = useState< CursorData[] >(
 		[]
 	);
@@ -63,76 +79,90 @@ export function useRenderCursors(
 			return;
 		}
 
+		// Pre-compute the overlay rect once, same for every user.
+		const overlayRect = overlayElement.getBoundingClientRect();
+		const overlayContext = {
+			editorDocument: blockEditorDocument,
+			overlayRect,
+		};
+
 		const results: CursorData[] = [];
 
-		sortedUsers.forEach( ( user: any ) => {
-			if ( user.isMe ) {
+		const hasOtherCollaborators = sortedUsers.some(
+			( u: ActiveCollaborator ) => ! u.isMe
+		);
+
+		sortedUsers.forEach( ( user: ActiveCollaborator ) => {
+			if ( user.isMe && ( ! showOwnCursor || ! hasOtherCollaborators ) ) {
 				return;
 			}
 
 			const selection = user.editorState?.selection ?? {
 				type: SelectionType.None,
 			};
-			const userName = user.collaboratorInfo.name;
-			const clientId = user.clientId;
-			const color = getAvatarBorderColor( user.collaboratorInfo.id );
-			const avatarUrl = getAvatarUrl( user.collaboratorInfo.avatar_urls );
 
-			let coords: {
-				x: number;
-				y: number;
-				height: number;
-			} | null = null;
+			let start: ResolvedSelection = {
+				richTextOffset: null,
+				localClientId: null,
+			};
+			let end: ResolvedSelection | undefined;
 
-			if ( selection.type === SelectionType.None ) {
-				// Nothing selected.
-			} else if ( selection.type === SelectionType.WholeBlock ) {
-				// Don't draw a cursor for a whole block selection.
-			} else if ( selection.type === SelectionType.Cursor ) {
+			if ( selection.type === SelectionType.Cursor ) {
 				try {
-					const { textIndex, localClientId } =
-						resolveSelection( selection );
-					if ( localClientId ) {
-						coords = getCursorPosition(
-							textIndex,
-							localClientId,
-							blockEditorDocument,
-							overlayElement
-						);
-					}
+					start = resolveSelection( selection );
 				} catch {
 					// Selection may reference a stale Yjs position.
+					return;
 				}
 			} else if (
 				selection.type === SelectionType.SelectionInOneBlock ||
 				selection.type === SelectionType.SelectionInMultipleBlocks
 			) {
 				try {
-					const { textIndex, localClientId } = resolveSelection( {
+					start = resolveSelection( {
 						type: SelectionType.Cursor,
 						cursorPosition: selection.cursorStartPosition,
 					} );
-					if ( localClientId ) {
-						coords = getCursorPosition(
-							textIndex,
-							localClientId,
-							blockEditorDocument,
-							overlayElement
-						);
-					}
+
+					end = resolveSelection( {
+						type: SelectionType.Cursor,
+						cursorPosition: selection.cursorEndPosition,
+					} );
 				} catch {
 					// Selection may reference a stale Yjs position.
+					return;
 				}
 			}
 
-			if ( coords ) {
-				results.push( {
+			const userName = user.collaboratorInfo.name;
+			const clientId = user.clientId;
+			const color = user.isMe
+				? 'var(--wp-admin-theme-color)'
+				: getAvatarBorderColor( user.collaboratorInfo.id );
+			const avatarUrl = getAvatarUrl( user.collaboratorInfo.avatar_urls );
+
+			const selectionVisual = computeSelectionVisual(
+				selection,
+				start,
+				end,
+				overlayContext
+			);
+
+			if ( selectionVisual.coords ) {
+				const cursorData: CursorData = {
 					userName,
 					clientId,
 					color,
 					avatarUrl,
-					...coords,
-				} );
+					isMe: user.isMe,
+					...selectionVisual.coords,
+				};
+
+				if ( selectionVisual.selectionRects ) {
+					cursorData.selectionRects = selectionVisual.selectionRects;
+				}
+
+				results.push( cursorData );
 			}
 		} );
 
@@ -142,211 +172,9 @@ export function useRenderCursors(
 		resolveSelection,
 		overlayElement,
 		sortedUsers,
+		showOwnCursor,
 		recomputeToken,
 	] );
 
 	return { cursors: cursorPositions, rerenderCursorsAfterDelay };
 }
-
-/**
- * Given a selection, returns the coordinates of the cursor in the block.
- *
- * @param absolutePositionIndex - The absolute position index
- * @param blockId               - The block ID
- * @param editorDocument        - The editor document
- * @param overlay               - The overlay element
- * @return The position of the cursor
- */
-const getCursorPosition = (
-	absolutePositionIndex: number | null,
-	blockId: string,
-	editorDocument: Document,
-	overlay: HTMLElement
-): { x: number; y: number; height: number } | null => {
-	if ( absolutePositionIndex === null ) {
-		// An absolute position index can be null if a cursor was set in a block that
-		// has since been deleted.
-		// Return null so we don't try to draw it.
-		return null;
-	}
-
-	const blockElement = editorDocument.querySelector(
-		`[data-block="${ blockId }"]`
-	) as HTMLElement;
-
-	if ( ! blockElement ) {
-		return null;
-	}
-
-	return (
-		getOffsetPositionInBlock(
-			blockElement,
-			absolutePositionIndex,
-			editorDocument,
-			overlay
-		) ?? null
-	);
-};
-
-/**
- * Given a block element and a character offset, returns the coordinates for drawing a visual cursor in the block.
- *
- * @param blockElement   - The block element
- * @param charOffset     - The character offset
- * @param editorDocument - The editor document
- * @param overlay        - The overlay element
- * @return The position of the cursor
- */
-const getOffsetPositionInBlock = (
-	blockElement: HTMLElement,
-	charOffset: number,
-	editorDocument: Document,
-	overlay: HTMLElement
-) => {
-	const { node, offset } = findInnerBlockOffset(
-		blockElement,
-		charOffset,
-		editorDocument
-	);
-
-	const cursorRange = editorDocument.createRange();
-
-	try {
-		cursorRange.setStart( node, offset );
-	} catch ( error ) {
-		return null;
-	}
-
-	// Ensure the range only represents single point in the DOM.
-	cursorRange.collapse( true );
-
-	const cursorRect = cursorRange.getBoundingClientRect();
-	const overlayRect = overlay.getBoundingClientRect();
-	const blockRect = blockElement.getBoundingClientRect();
-
-	let cursorX = 0;
-	let cursorY = 0;
-
-	if (
-		cursorRect.x === 0 &&
-		cursorRect.y === 0 &&
-		cursorRect.width === 0 &&
-		cursorRect.height === 0
-	) {
-		// This can happen for empty blocks.
-		cursorX = blockRect.left - overlayRect.left;
-		cursorY = blockRect.top - overlayRect.top;
-	} else {
-		cursorX = cursorRect.left - overlayRect.left;
-		cursorY = cursorRect.top - overlayRect.top;
-	}
-
-	let cursorHeight = cursorRect.height;
-	if ( cursorHeight === 0 ) {
-		const view = editorDocument.defaultView ?? window;
-		cursorHeight =
-			parseInt( view.getComputedStyle( blockElement ).lineHeight, 10 ) ||
-			blockRect.height;
-	}
-
-	return {
-		x: cursorX,
-		y: cursorY,
-		height: cursorHeight,
-	};
-};
-
-const MAX_NODE_OFFSET_COUNT = 1000;
-
-/**
- * Given a block element and a character offset, returns an exact inner node and offset for use in a range.
- *
- * @param blockElement   - The block element
- * @param offset         - The character offset
- * @param editorDocument - The editor document
- * @return The node and offset of the character at the offset
- */
-const findInnerBlockOffset = (
-	blockElement: HTMLElement,
-	offset: number,
-	editorDocument: Document
-) => {
-	const treeWalker = editorDocument.createTreeWalker(
-		blockElement,
-		NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT // eslint-disable-line no-bitwise
-	);
-
-	let currentOffset = 0;
-	let lastTextNode: Node | null = null;
-
-	let node: Node | null = null;
-	let nodeCount = 1;
-
-	while ( ( node = treeWalker.nextNode() ) ) {
-		nodeCount++;
-
-		if ( nodeCount > MAX_NODE_OFFSET_COUNT ) {
-			// If we've walked too many nodes, return the last text node or the beginning of the block.
-			if ( lastTextNode ) {
-				return { node: lastTextNode, offset: 0 };
-			}
-			return { node: blockElement, offset: 0 };
-		}
-
-		const nodeLength = node.nodeValue?.length ?? 0;
-
-		if ( node.nodeType === Node.ELEMENT_NODE ) {
-			if ( node.nodeName === 'BR' ) {
-				// Treat <br> as a single "\n" character.
-
-				if ( currentOffset + 1 >= offset ) {
-					// If the <br> occurs right on the target offset, return the next text node.
-					const nodeAfterBr = treeWalker.nextNode();
-
-					if ( nodeAfterBr?.nodeType === Node.TEXT_NODE ) {
-						return { node: nodeAfterBr, offset: 0 };
-					} else if ( lastTextNode ) {
-						// If there's no text node after the <br>, return the end offset of the last text node.
-						return {
-							node: lastTextNode,
-							offset: lastTextNode.nodeValue?.length ?? 0,
-						};
-					}
-					// Just in case, if there's no last text node, return the beginning of the block.
-					return { node: blockElement, offset: 0 };
-				}
-
-				// The <br> is before the target offset. Count it as a single character.
-				currentOffset += 1;
-				continue;
-			} else {
-				// Skip other element types.
-				continue;
-			}
-		}
-
-		if ( nodeLength === 0 ) {
-			// Skip empty nodes.
-			continue;
-		}
-
-		if ( currentOffset + nodeLength >= offset ) {
-			// This node exceeds the target offset. Return the node and the position of the offset within it.
-			return { node, offset: offset - currentOffset };
-		}
-
-		currentOffset += nodeLength;
-
-		if ( node.nodeType === Node.TEXT_NODE ) {
-			lastTextNode = node;
-		}
-	}
-
-	if ( lastTextNode && lastTextNode.nodeValue?.length ) {
-		// We didn't reach the target offset. Return the last text node's last character.
-		return { node: lastTextNode, offset: lastTextNode.nodeValue.length };
-	}
-
-	// We didn't find any text nodes. Return the beginning of the block.
-	return { node: blockElement, offset: 0 };
-};

package/src/components/collaborators-presence/avatar/styles.scss

@@ -5,13 +5,14 @@
 // fallback matching the default WordPress admin blue.
 $-accent-color: var(--wp-admin-theme-color, #3858e9);
 
+// overflow: clip is intentionally omitted here — .editor-avatar__image handles
+// its own circular clip. Removing overflow from this container allows the inset
+// box-shadow on __image to render without being clipped by the parent.
 .editor-avatar {
 	position: relative;
 	display: inline-flex;
 	align-items: center;
 	border-radius: $radius-full;
-	overflow: hidden;
-	overflow: clip;
 	flex-shrink: 0;
 	box-shadow: 0 0 0 var(--wp-admin-border-width-focus) $white, $elevation-x-small;
 }
@@ -37,8 +38,20 @@ $-accent-color: var(--wp-admin-theme-color, #3858e9);
 
 	.has-avatar-border-color > & {
 		border: var(--wp-admin-border-width-focus) solid var(--editor-avatar-outline-color);
-		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) $white;
 		background-clip: padding-box;
+
+		// Inner contrast ring rendered as a pseudo-element so it paints above
+		// the absolutely-positioned <img>. An inset box-shadow would be
+		// covered by the image content layer.
+		&::after {
+			content: "";
+			position: absolute;
+			inset: 0;
+			border-radius: inherit;
+			box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus, 2px) $white;
+			pointer-events: none;
+			z-index: 1;
+		}
 	}
 }
 
@@ -66,8 +79,11 @@ $-accent-color: var(--wp-admin-theme-color, #3858e9);
 	font-size: $font-size-x-small;
 	font-weight: $font-weight-medium;
 	border: 0;
-	box-shadow: none;
 	background-clip: border-box;
+
+	&::after {
+		content: none;
+	}
 }
 
 .editor-avatar:not(.has-src).has-avatar-border-color > .editor-avatar__image {