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

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

@@ -4,31 +4,53 @@
 import {
 	privateApis as coreDataPrivateApis,
 	SelectionType,
+	type PostEditorAwarenessState,
 } from '@wordpress/core-data';
-import { useEffect, useRef } from '@wordpress/element';
+import { useEffect, useRef, useState } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import { unlock } from '../../lock-unlock';
 import { getAvatarBorderColor } from '../collab-sidebar/utils';
+import { getAvatarUrl } from './get-avatar-url';
+import { useDebouncedRecompute } from './use-debounced-recompute';
 
 const { useActiveCollaborators, useResolvedSelection } =
 	unlock( coreDataPrivateApis );
 
+export interface BlockHighlightData {
+	blockId: string;
+	userName: string;
+	avatarUrl?: string;
+	color: string;
+	x: number;
+	y: number;
+}
+
 /**
- * Custom hook for highlighting selected blocks in the editor
- * @param blockEditorDocument - Ref to the block editor document, used to directly style block elements.
- * @param postId              - The ID of the post
- * @param postType            - The type of the post
+ * Custom hook for highlighting selected blocks in the editor and computing
+ * their positions for rendering avatar labels in the overlay.
+ *
+ * @param overlayElement      - The overlay element used as position reference.
+ * @param blockEditorDocument - Ref to the block editor document.
+ * @param postId              - The ID of the post.
+ * @param postType            - The type of the post.
+ * @param delayMs             - Milliseconds to wait before recomputing highlight positions.
+ * @return Highlight data for rendering and a delayed recompute function.
  */
 export function useBlockHighlighting(
+	overlayElement: HTMLElement | null,
 	blockEditorDocument: Document | null,
 	postId: number | null,
-	postType: string | null
-) {
+	postType: string | null,
+	delayMs: number
+): {
+	highlights: BlockHighlightData[];
+	rerenderHighlightsAfterDelay: () => () => void;
+} {
 	const highlightedBlockIds = useRef< Set< string > >( new Set() );
-	const userStates = useActiveCollaborators(
+	const userStates: PostEditorAwarenessState[] = useActiveCollaborators(
 		postId ?? null,
 		postType ?? null
 	);
@@ -37,15 +59,78 @@ export function useBlockHighlighting(
 		postType ?? null
 	);
 
-	// Draw block highlights
+	const [ highlights, setHighlights ] = useState< BlockHighlightData[] >(
+		[]
+	);
+
+	// Bump this counter to force the effect to re-run (e.g. after a layout shift).
+	const [ recomputeToken, rerenderHighlightsAfterDelay ] =
+		useDebouncedRecompute( delayMs );
+
+	// All DOM mutations and position computations live inside useEffect.
 	useEffect( () => {
-		// Don't do anything if editor is not rendered yet.
-		if ( blockEditorDocument === null ) {
+		if ( ! blockEditorDocument ) {
+			setHighlights( [] );
 			return;
 		}
 
-		const unhighlightBlocks = ( blockIds: string[] ) => {
-			blockIds.forEach( ( blockId ) => {
+		// Capture the ref value so the cleanup closure sees the same Set
+		// even if a later render replaces it.
+		const currentHighlightedIds = highlightedBlockIds.current;
+
+		// Deduplicate by blockId — when multiple collaborators select the
+		// same block, only the first one gets the highlight and avatar label.
+		const seen = new Set< string >();
+		const blocksToHighlight = userStates
+			.filter(
+				( userState ) =>
+					! userState.isMe &&
+					userState.editorState?.selection?.type ===
+						SelectionType.WholeBlock
+			)
+			.map( ( userState ) => {
+				let localClientId;
+				try {
+					( { localClientId } = resolveSelection(
+						userState.editorState?.selection
+					) );
+				} catch {
+					return null;
+				}
+
+				if ( ! localClientId ) {
+					return null;
+				}
+
+				return {
+					blockId: localClientId,
+					color: getAvatarBorderColor(
+						userState.collaboratorInfo.id
+					),
+					userName: userState.collaboratorInfo.name,
+					avatarUrl: getAvatarUrl(
+						userState.collaboratorInfo.avatar_urls
+					),
+				};
+			} )
+			.filter( ( block ): block is NonNullable< typeof block > => {
+				if ( ! block ) {
+					return false;
+				}
+				if ( seen.has( block.blockId ) ) {
+					return false;
+				}
+				seen.add( block.blockId );
+				return true;
+			} );
+
+		// Unhighlight blocks that are no longer selected.
+		const selectedBlockIds = new Set(
+			blocksToHighlight.map( ( block ) => block.blockId )
+		);
+
+		for ( const blockId of currentHighlightedIds ) {
+			if ( ! selectedBlockIds.has( blockId ) ) {
 				const blockElement = getBlockElementById(
 					blockEditorDocument,
 					blockId
@@ -58,51 +143,16 @@ export function useBlockHighlighting(
 					);
 				}
 
-				highlightedBlockIds.current.delete( blockId );
-			} );
-		};
-
-		const blocksToHighlight = userStates
-			.map( ( userState: any ) => {
-				const isWholeBlockSelected =
-					userState.editorState?.selection?.type ===
-					SelectionType.WholeBlock;
-				const shouldDrawUser = ! userState.isMe;
-
-				if ( isWholeBlockSelected && shouldDrawUser ) {
-					const { localClientId } = resolveSelection(
-						userState.editorState?.selection
-					);
-
-					if ( ! localClientId ) {
-						return null;
-					}
-
-					return {
-						blockId: localClientId,
-						color: getAvatarBorderColor(
-							userState.collaboratorInfo.id
-						),
-					};
-				}
-
-				return null;
-			} )
-			.filter( ( block: any ) => block !== null );
-
-		// Unhighlight blocks that are no longer highlighted.
-		const selectedBlockIds = blocksToHighlight.map(
-			( block: any ) => block.blockId
-		);
-		const blocksIdsToUnhighlight = Array.from(
-			highlightedBlockIds.current
-		).filter( ( blockId ) => ! selectedBlockIds.includes( blockId ) );
+				currentHighlightedIds.delete( blockId );
+			}
+		}
 
-		unhighlightBlocks( blocksIdsToUnhighlight );
+		// Highlight blocks and compute positions for avatar labels.
+		const results: BlockHighlightData[] = [];
+		const overlayRect = overlayElement?.getBoundingClientRect() ?? null;
 
-		// Highlight blocks that are currently highlighted.
-		blocksToHighlight.forEach( ( blockColorPair: any ) => {
-			const { color, blockId } = blockColorPair;
+		blocksToHighlight.forEach( ( block ) => {
+			const { color, blockId, userName, avatarUrl } = block;
 			const blockElement = getBlockElementById(
 				blockEditorDocument,
 				blockId
@@ -112,16 +162,49 @@ export function useBlockHighlighting(
 				return;
 			}
 
-			if ( blockElement ) {
-				blockElement.classList.add( 'is-collaborator-selected' );
-				blockElement.style.setProperty(
-					'--collaborator-outline-color',
-					color
-				);
-				highlightedBlockIds.current.add( blockId );
+			blockElement.classList.add( 'is-collaborator-selected' );
+			blockElement.style.setProperty(
+				'--collaborator-outline-color',
+				color
+			);
+			currentHighlightedIds.add( blockId );
+
+			if ( overlayRect ) {
+				const blockRect = blockElement.getBoundingClientRect();
+
+				results.push( {
+					blockId,
+					userName,
+					avatarUrl,
+					color,
+					x: blockRect.left - overlayRect.left,
+					y: blockRect.top - overlayRect.top,
+				} );
 			}
 		} );
-	}, [ userStates, blockEditorDocument, resolveSelection ] );
+
+		setHighlights( results );
+
+		// Clean up all highlights on unmount.
+		return () => {
+			for ( const blockId of currentHighlightedIds ) {
+				const el = getBlockElementById( blockEditorDocument, blockId );
+				if ( el ) {
+					el.classList.remove( 'is-collaborator-selected' );
+					el.style.removeProperty( '--collaborator-outline-color' );
+				}
+			}
+			currentHighlightedIds.clear();
+		};
+	}, [
+		userStates,
+		blockEditorDocument,
+		overlayElement,
+		recomputeToken,
+		resolveSelection,
+	] );
+
+	return { highlights, rerenderHighlightsAfterDelay };
 }
 
 const getBlockElementById = (

package/src/components/collaborators-overlay/use-debounced-recompute.ts

@@ -0,0 +1,32 @@
+import { useCallback, useRef, useState } from '@wordpress/element';
+
+/**
+ * Returns a recompute token and a debounced callback that bumps it.
+ * Rapid successive calls cancel the previous pending timeout so only one
+ * recompute fires, `delayMs` after the last call.
+ *
+ * @param delayMs - Milliseconds to wait before bumping the recompute token.
+ * @return A tuple of [recomputeToken, rerenderAfterDelay].
+ */
+export function useDebouncedRecompute(
+	delayMs: number
+): [ number, () => () => void ] {
+	const [ recomputeToken, setRecomputeToken ] = useState( 0 );
+	const timeoutRef = useRef< ReturnType< typeof setTimeout > | null >( null );
+
+	const rerenderAfterDelay = useCallback( () => {
+		if ( timeoutRef.current ) {
+			clearTimeout( timeoutRef.current );
+		}
+		timeoutRef.current = setTimeout( () => {
+			setRecomputeToken( ( t ) => t + 1 );
+		}, delayMs );
+		return () => {
+			if ( timeoutRef.current ) {
+				clearTimeout( timeoutRef.current );
+			}
+		};
+	}, [ delayMs ] );
+
+	return [ recomputeToken, rerenderAfterDelay ];
+}

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

@@ -2,11 +2,12 @@ import {
 	privateApis as coreDataPrivateApis,
 	SelectionType,
 } from '@wordpress/core-data';
-import { useEffect, useMemo, useState } from '@wordpress/element';
+import { useEffect, useState } from '@wordpress/element';
 
 import { unlock } from '../../lock-unlock';
 import { getAvatarUrl } from './get-avatar-url';
 import { getAvatarBorderColor } from '../collab-sidebar/utils';
+import { useDebouncedRecompute } from './use-debounced-recompute';
 
 const { useActiveCollaborators, useResolvedSelection } =
 	unlock( coreDataPrivateApis );
@@ -28,13 +29,15 @@ export interface CursorData {
  * @param blockEditorDocument - The block editor document
  * @param postId              - The ID of the post
  * @param postType            - The type of the post
+ * @param delayMs             - Milliseconds to wait before recomputing cursor positions.
  * @return An array of cursor data for rendering, and a function to trigger a delayed recompute.
  */
 export function useRenderCursors(
 	overlayElement: HTMLElement | null,
 	blockEditorDocument: Document | null,
 	postId: number | null,
-	postType: string | null
+	postType: string | null,
+	delayMs: number
 ): { cursors: CursorData[]; rerenderCursorsAfterDelay: () => () => void } {
 	const sortedUsers = useActiveCollaborators(
 		postId ?? null,
@@ -49,41 +52,44 @@ export function useRenderCursors(
 		[]
 	);
 
-	const computeCursors = useMemo(
-		() => () => {
-			if ( ! overlayElement || ! blockEditorDocument ) {
-				setCursorPositions( [] );
-				return;
-			}
+	// Bump this counter to force the effect to re-run (e.g. after a layout shift).
+	const [ recomputeToken, rerenderCursorsAfterDelay ] =
+		useDebouncedRecompute( delayMs );
 
-			const results: CursorData[] = [];
+	// All DOM position computations live inside useEffect.
+	useEffect( () => {
+		if ( ! overlayElement || ! blockEditorDocument ) {
+			setCursorPositions( [] );
+			return;
+		}
 
-			sortedUsers.forEach( ( user: any ) => {
-				if ( user.isMe ) {
-					return;
-				}
+		const results: CursorData[] = [];
 
-				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;
-
-				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 ) {
+		sortedUsers.forEach( ( user: any ) => {
+			if ( user.isMe ) {
+				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;
+
+			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 ) {
+				try {
 					const { textIndex, localClientId } =
 						resolveSelection( selection );
 					if ( localClientId ) {
@@ -94,10 +100,14 @@ export function useRenderCursors(
 							overlayElement
 						);
 					}
-				} else if (
-					selection.type === SelectionType.SelectionInOneBlock ||
-					selection.type === SelectionType.SelectionInMultipleBlocks
-				) {
+				} catch {
+					// Selection may reference a stale Yjs position.
+				}
+			} else if (
+				selection.type === SelectionType.SelectionInOneBlock ||
+				selection.type === SelectionType.SelectionInMultipleBlocks
+			) {
+				try {
 					const { textIndex, localClientId } = resolveSelection( {
 						type: SelectionType.Cursor,
 						cursorPosition: selection.cursorStartPosition,
@@ -110,33 +120,30 @@ export function useRenderCursors(
 							overlayElement
 						);
 					}
+				} catch {
+					// Selection may reference a stale Yjs position.
 				}
+			}
 
-				if ( coords ) {
-					results.push( {
-						userName,
-						clientId,
-						color,
-						avatarUrl,
-						...coords,
-					} );
-				}
-			} );
-
-			setCursorPositions( results );
-		},
-		[ blockEditorDocument, resolveSelection, overlayElement, sortedUsers ]
-	);
-
-	useEffect( computeCursors, [ computeCursors ] );
+			if ( coords ) {
+				results.push( {
+					userName,
+					clientId,
+					color,
+					avatarUrl,
+					...coords,
+				} );
+			}
+		} );
 
-	const rerenderCursorsAfterDelay = useMemo(
-		() => () => {
-			const timeout = setTimeout( computeCursors, 500 );
-			return () => clearTimeout( timeout );
-		},
-		[ computeCursors ]
-	);
+		setCursorPositions( results );
+	}, [
+		blockEditorDocument,
+		resolveSelection,
+		overlayElement,
+		sortedUsers,
+		recomputeToken,
+	] );
 
 	return { cursors: cursorPositions, rerenderCursorsAfterDelay };
 }
@@ -236,11 +243,10 @@ const getOffsetPositionInBlock = (
 
 	let cursorHeight = cursorRect.height;
 	if ( cursorHeight === 0 ) {
+		const view = editorDocument.defaultView ?? window;
 		cursorHeight =
-			parseInt(
-				window.getComputedStyle( blockElement ).lineHeight,
-				10
-			) || blockRect.height;
+			parseInt( view.getComputedStyle( blockElement ).lineHeight, 10 ) ||
+			blockRect.height;
 	}
 
 	return {

package/src/components/collaborators-presence/avatar/component.tsx

@@ -0,0 +1,123 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+import { colord, extend } from 'colord';
+import a11yPlugin from 'colord/plugins/a11y';
+
+extend( [ a11yPlugin ] );
+
+/**
+ * WordPress dependencies
+ */
+import { Icon, Tooltip } from '@wordpress/components';
+import { useMemo } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { AvatarProps } from './types';
+import { useImageLoadingStatus } from './use-image-loading-status';
+
+// Runtime equivalents of @wordpress/base-styles tokens ($gray-900, $white).
+const GRAY_900 = '#1e1e1e';
+const WHITE = '#fff';
+
+function Avatar( {
+	className,
+	src,
+	name,
+	label,
+	variant,
+	size = 'default',
+	borderColor,
+	dimmed = false,
+	statusIndicator,
+	style,
+	...props
+}: AvatarProps &
+	Omit< React.HTMLAttributes< HTMLDivElement >, keyof AvatarProps > ) {
+	const {
+		status: imageStatus,
+		handleLoad,
+		handleError,
+	} = useImageLoadingStatus( src );
+	const imageLoaded = imageStatus === 'loaded';
+
+	const showBadge = variant === 'badge' && !! name;
+	const initials = name
+		? name
+				.split( /\s+/ )
+				.slice( 0, 2 )
+				.map( ( word ) => word[ 0 ] )
+				.join( '' )
+				.toUpperCase()
+		: undefined;
+	const nameColor = useMemo(
+		() =>
+			borderColor &&
+			colord( borderColor ).isReadable( GRAY_900, {
+				level: 'AA',
+				size: 'normal',
+			} )
+				? GRAY_900
+				: WHITE,
+		[ borderColor ]
+	);
+
+	const customProperties = {
+		...style,
+		...( borderColor
+			? {
+					'--editor-avatar-outline-color': borderColor,
+					'--editor-avatar-name-color': nameColor,
+			  }
+			: {} ),
+	} as React.CSSProperties;
+
+	const avatar = (
+		<div
+			className={ clsx( 'editor-avatar', className, {
+				'has-avatar-border-color': !! borderColor,
+				'has-src': imageLoaded,
+				'is-badge': showBadge,
+				'is-small': size === 'small',
+				'is-dimmed': dimmed,
+			} ) }
+			style={ customProperties }
+			role={ name ? 'img' : undefined }
+			aria-label={ name || undefined }
+			{ ...props }
+		>
+			<span className="editor-avatar__image">
+				{ src && (
+					<img
+						src={ src }
+						alt=""
+						crossOrigin="anonymous"
+						className="editor-avatar__img"
+						onLoad={ handleLoad }
+						onError={ handleError }
+					/>
+				) }
+				{ ! imageLoaded && initials }
+			</span>
+			{ dimmed && !! statusIndicator && (
+				<span className="editor-avatar__status-indicator">
+					<Icon icon={ statusIndicator } />
+				</span>
+			) }
+			{ showBadge && (
+				<span className="editor-avatar__name">{ label || name }</span>
+			) }
+		</div>
+	);
+
+	if ( name && ( ! showBadge || label ) ) {
+		return <Tooltip text={ name }>{ avatar }</Tooltip>;
+	}
+
+	return avatar;
+}
+
+export default Avatar;

package/src/components/collaborators-presence/avatar/index.ts

@@ -0,0 +1,2 @@
+export { default } from './component';
+export type { AvatarProps } from './types';