@wordpress/editor 14.40.2-next.v.202602271551.0 → 14.40.2

package/src/components/collaborators-overlay/cursor-registry.ts

@@ -0,0 +1,96 @@
+interface ScrollToCursorOptions {
+	behavior?: ScrollBehavior;
+	block?: ScrollLogicalPosition;
+	inline?: ScrollLogicalPosition;
+	highlightDuration?: number;
+}
+
+/**
+ * Cursor Registry
+ * ===
+ * This registry stores references to cursor elements so that we can access them
+ * in different parts of the component tree. This would more ideally be solved
+ * with React context or state in the awareness store, but:
+ *
+ * 1. EditorPresence and BlockCanvasCover slot/fill break context propagation. We
+ *    don't currently have a way to provide context to both the slot and fill.
+ * 2. Storing pointers to the cursor elements in the awareness store might be a
+ *    better solution, but would require broader refactoring.
+ *
+ * For now, we create a single instance of this registry and pass it down to the
+ * components that need it. It's important that we create a single instance and
+ * not a new instance per component or render; use useState with a lazy
+ * initializer to accomplish this.
+ */
+
+function highlightCursor( element: HTMLElement, duration: number ): void {
+	element.classList.add( 'collaborators-overlay-cursor-highlighted' );
+
+	setTimeout( () => {
+		element.classList.remove( 'collaborators-overlay-cursor-highlighted' );
+	}, duration );
+}
+
+export function createCursorRegistry() {
+	const cursorMap = new Map< number, HTMLElement >();
+
+	return {
+		/**
+		 * Register a cursor element when it's created.
+		 *
+		 * @param clientId - The clientId of the cursor to register.
+		 * @param element  - The cursor element to register.
+		 */
+		registerCursor( clientId: number, element: HTMLElement ): void {
+			cursorMap.set( clientId, element );
+		},
+
+		/**
+		 * Unregister a cursor element when it's removed.
+		 *
+		 * @param clientId - The clientId of the cursor to unregister.
+		 */
+		unregisterCursor( clientId: number ): void {
+			cursorMap.delete( clientId );
+		},
+
+		/**
+		 * Scroll to a cursor by clientId.
+		 *
+		 * @param clientId - The clientId of the cursor to scroll to.
+		 * @param options  - The options for the scroll.
+		 * @return true if cursor was found and scrolled to, false otherwise.
+		 */
+		scrollToCursor(
+			clientId: number,
+			options?: ScrollToCursorOptions
+		): boolean {
+			const cursorElement = cursorMap.get( clientId );
+
+			if ( ! cursorElement ) {
+				return false;
+			}
+
+			cursorElement.scrollIntoView( {
+				behavior: options?.behavior ?? 'smooth',
+				block: options?.block ?? 'center',
+				inline: options?.inline ?? 'nearest',
+			} );
+
+			if ( options?.highlightDuration ) {
+				highlightCursor( cursorElement, options.highlightDuration );
+			}
+
+			return true;
+		},
+
+		/**
+		 * Clear the registry.
+		 */
+		removeAll(): void {
+			cursorMap.clear();
+		},
+	};
+}
+
+export type CursorRegistry = ReturnType< typeof createCursorRegistry >;

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

@@ -9,22 +9,29 @@ import { privateApis } from '@wordpress/block-editor';
  */
 import { unlock } from '../../lock-unlock';
 import { Overlay } from './overlay';
+import { type CursorRegistry } from './cursor-registry';
 
 const { BlockCanvasCover } = unlock( privateApis );
 
 interface Props {
 	postId: number | null;
 	postType: string | null;
+	cursorRegistry?: CursorRegistry;
 }
 
 /**
  * Collaborators Overlay component
- * @param props          - The props for the CollaboratorsOverlay component
- * @param props.postId   - The ID of the post
- * @param props.postType - The type of the post
+ * @param props                - The props for the CollaboratorsOverlay component
+ * @param props.postId         - The ID of the post
+ * @param props.postType       - The type of the post
+ * @param props.cursorRegistry - The shared cursor registry
  * @return The CollaboratorsOverlay component
  */
-export function CollaboratorsOverlay( { postId, postType }: Props ) {
+export function CollaboratorsOverlay( {
+	postId,
+	postType,
+	cursorRegistry,
+}: Props ) {
 	return (
 		<BlockCanvasCover.Fill>
 			{ ( {
@@ -36,6 +43,7 @@ export function CollaboratorsOverlay( { postId, postType }: Props ) {
 					blockEditorDocument={ containerRef.current?.ownerDocument }
 					postId={ postId }
 					postType={ postType }
+					cursorRegistry={ cursorRegistry }
 				/>
 			) }
 		</BlockCanvasCover.Fill>

package/src/components/collaborators-overlay/overlay-iframe-styles.ts

@@ -0,0 +1,131 @@
+/**
+ * CSS for the collaborators overlay — cursor indicators, block highlights,
+ * and positioning of Avatar labels inside the editor canvas iframe.
+ */
+
+import {
+	BORDER_WIDTH,
+	BORDER_WIDTH_FOCUS_FALLBACK,
+	ELEVATION_X_SMALL,
+	GRID_UNIT_05,
+	GRID_UNIT_10,
+	WHITE,
+} from './collaborator-styles';
+
+export const OVERLAY_IFRAME_STYLES = `
+.block-canvas-cover {
+	position: absolute;
+	top: 0;
+	left: 0;
+	width: 100%;
+	height: 100%;
+	pointer-events: none;
+	z-index: 20000;
+}
+.block-canvas-cover .collaborators-overlay-full {
+	position: absolute;
+	top: 0;
+	left: 0;
+	width: 100%;
+	height: 100%;
+}
+.block-canvas-cover .collaborators-overlay-fixed {
+	position: fixed;
+	width: 100%;
+	height: 100%;
+}
+.collaborators-overlay-user {
+	position: absolute;
+}
+/* Cursor lines render below avatar labels across all users. The parent
+   .collaborators-overlay-user has no z-index so it does not create a
+   stacking context — children participate in the shared overlay context. */
+.collaborators-overlay-user-cursor {
+	position: absolute;
+	z-index: 0;
+	width: ${ BORDER_WIDTH_FOCUS_FALLBACK };
+	border-radius: ${ BORDER_WIDTH };
+	outline: ${ BORDER_WIDTH } solid ${ WHITE };
+	box-shadow: ${ ELEVATION_X_SMALL };
+	animation: collaborators-overlay-cursor-blink 1s infinite;
+}
+.collaborators-overlay-selection-rect {
+	position: absolute;
+	opacity: 0.15;
+	pointer-events: none;
+	border-radius: 2px;
+}
+
+/* Overlay-specific positioning applied to the Avatar cursor label. */
+.collaborators-overlay-user-label.editor-avatar {
+	position: absolute;
+	z-index: 1;
+	transform: translate(-11px, -100%);
+	margin-top: -${ GRID_UNIT_05 };
+	pointer-events: auto;
+	overflow: visible;
+	width: max-content;
+}
+/* Avatar positioned above a highlighted block as a label. */
+.collaborators-overlay-block-label.editor-avatar {
+	position: absolute;
+	z-index: 1;
+	transform: translateY(calc(-100% - ${ GRID_UNIT_10 }));
+	pointer-events: auto;
+	overflow: visible;
+	width: max-content;
+}
+
+@keyframes collaborators-overlay-cursor-blink {
+	0%, 45% { opacity: 1; }
+	55%, 95% { opacity: 0; }
+	100% { opacity: 1; }
+}
+.collaborators-overlay-cursor-highlighted .collaborators-overlay-user-cursor {
+	animation: collaborators-overlay-cursor-highlight 0.6s ease-in-out 3;
+}
+.collaborators-overlay-cursor-highlighted .collaborators-overlay-user-label {
+	animation: collaborators-overlay-label-highlight 0.6s ease-in-out 3;
+}
+@keyframes collaborators-overlay-cursor-highlight {
+	0%, 100% {
+		transform: scale(1);
+		filter: drop-shadow(0 0 0 transparent);
+	}
+	50% {
+		transform: scale(1.2);
+		filter: drop-shadow(0 0 8px currentColor);
+	}
+}
+@keyframes collaborators-overlay-label-highlight {
+	0%, 100% {
+		transform: translate(-11px, -100%) scale(1);
+		filter: drop-shadow(0 0 0 transparent);
+	}
+	50% {
+		transform: translate(-11px, -100%) scale(1.1);
+		filter: drop-shadow(0 0 6px currentColor);
+	}
+}
+.block-editor-block-list__block.is-collaborator-selected:not(:focus)::after {
+	content: "";
+	position: absolute;
+	pointer-events: none;
+	top: 0;
+	right: 0;
+	bottom: 0;
+	left: 0;
+	outline-color: var(--collaborator-outline-color);
+	outline-style: solid;
+	outline-width: calc(var(--wp-admin-border-width-focus) / var(--wp-block-editor-iframe-zoom-out-scale, 1));
+	outline-offset: calc(-1 * var(--wp-admin-border-width-focus) / var(--wp-block-editor-iframe-zoom-out-scale, 1));
+	box-shadow: inset 0 0 0 calc((var(--wp-admin-border-width-focus) / var(--wp-block-editor-iframe-zoom-out-scale, 1)) + 0.5px) rgba(${ WHITE }, 0.7);
+	z-index: 1;
+}
+@media (prefers-reduced-motion: reduce) {
+	.collaborators-overlay-user-label,
+	.collaborators-overlay-user-cursor {
+		animation: none;
+	}
+}
+`;

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

@@ -1,208 +1,29 @@
-import { privateApis as componentsPrivateApis } from '@wordpress/components';
 import { useResizeObserver, useMergeRefs } from '@wordpress/compose';
-import { useEffect, useState } from '@wordpress/element';
+import { useCallback, useEffect, useRef, useState } from '@wordpress/element';
+import { __ } from '@wordpress/i18n';
 
-import { unlock } from '../../lock-unlock';
+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';
-import { ELEVATION_X_SMALL } from './collaborator-styles';
+import { type CursorRegistry } from './cursor-registry';
 
-const { Avatar } = unlock( componentsPrivateApis );
+// Milliseconds to wait after a change before recomputing cursor positions.
+const RERENDER_DELAY_MS = 500;
 
-// wp-components styles are excluded from the editor canvas iframe, so the
-// Avatar component's SCSS is not available there. We inject compiled versions
-// of the relevant rules alongside the overlay-specific positioning styles.
-const COLLABORATORS_OVERLAY_STYLES = `
-.block-canvas-cover {
-	position: absolute;
-	top: 0;
-	left: 0;
-	width: 100%;
-	height: 100%;
-	pointer-events: none;
-	z-index: 20000;
-}
-.block-canvas-cover .collaborators-overlay-full {
-	position: absolute;
-	top: 0;
-	left: 0;
-	width: 100%;
-	height: 100%;
-}
-.block-canvas-cover .collaborators-overlay-fixed {
-	position: fixed;
-	width: 100%;
-	height: 100%;
-}
-.collaborators-overlay-user {
-	position: absolute;
-}
-.collaborators-overlay-user-cursor {
-	position: absolute;
-	width: 2px;
-	border-radius: 1px;
-	outline: 1px solid #fff;
-	box-shadow: ${ ELEVATION_X_SMALL };
-	animation: collaborators-overlay-cursor-blink 1s infinite;
-}
-
-/* ── Avatar component (compiled from packages/components/src/avatar/styles.scss) ── */
-.components-avatar {
-	display: inline-flex;
-	align-items: center;
-	border-radius: 9999px;
-	overflow: clip;
-	flex-shrink: 0;
-	background-color: var(--wp-components-color-accent, var(--wp-admin-theme-color, #3858e9));
-	box-shadow: 0 0 0 var(--wp-admin-border-width-focus, 2px) #fff, ${ ELEVATION_X_SMALL };
-}
-.components-avatar__image {
-	box-sizing: border-box;
-	position: relative;
-	width: 32px;
-	height: 32px;
-	border-radius: 9999px;
-	border: 0;
-	background-color: var(--wp-components-color-accent, var(--wp-admin-theme-color, #3858e9));
-	overflow: clip;
-	flex-shrink: 0;
-	font-size: 0;
-	color: #fff;
-}
-.is-small > .components-avatar__image {
-	width: 24px;
-	height: 24px;
-}
-.has-src > .components-avatar__image {
-	background-image: var(--components-avatar-url);
-	background-size: cover;
-	background-position: center;
-}
-.has-avatar-border-color > .components-avatar__image {
-	border: var(--wp-admin-border-width-focus, 2px) solid var(--components-avatar-outline-color);
-	box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus, 2px) #fff;
-	background-clip: padding-box;
-}
-.components-avatar:not(.has-src) > .components-avatar__image {
-	display: flex;
-	align-items: center;
-	justify-content: center;
-	font-size: 11px;
-	font-weight: 499;
-	border: 0;
-	box-shadow: none;
-	background-clip: border-box;
-}
-.components-avatar:not(.has-src).has-avatar-border-color > .components-avatar__image {
-	background-color: var(--components-avatar-outline-color);
-}
-.components-avatar__name {
-	font-size: 13px;
-	line-height: 20px;
-	color: #fff;
-	min-width: 0;
-	padding-bottom: 2px;
-	overflow: hidden;
-	opacity: 0;
-	white-space: nowrap;
-	transition: opacity 0.15s cubic-bezier(0.15, 0, 0.15, 1);
-}
-.components-avatar.has-badge {
-	display: inline-grid;
-	grid-template-columns: min-content 0fr;
-	column-gap: 0;
-	padding-inline-end: 0;
-	transition:
-		grid-template-columns 0.3s cubic-bezier(0.15, 0, 0.15, 1),
-		column-gap 0.3s cubic-bezier(0.15, 0, 0.15, 1),
-		padding-inline-end 0.3s cubic-bezier(0.15, 0, 0.15, 1);
-}
-.components-avatar.has-badge:hover {
-	grid-template-columns: min-content 1fr;
-	column-gap: 4px;
-	padding-inline-end: 8px;
-	transition-timing-function: cubic-bezier(0.85, 0, 0.85, 1);
-}
-.components-avatar.has-badge:hover .components-avatar__name {
-	opacity: 1;
-	transition-timing-function: cubic-bezier(0.85, 0, 0.85, 1);
-}
-.components-avatar.has-badge.has-avatar-border-color {
-	background-color: var(--components-avatar-outline-color);
-}
-/* ── end Avatar ── */
-
-/* Overlay-specific positioning applied to the Avatar cursor label. */
-.collaborators-overlay-user-label.components-avatar {
-	position: absolute;
-	transform: translate(-11px, -100%);
-	margin-top: -4px;
-	pointer-events: auto;
-	overflow: visible;
-	width: max-content;
-}
-
-@keyframes collaborators-overlay-cursor-blink {
-	0%, 45% { opacity: 1; }
-	55%, 95% { opacity: 0; }
-	100% { opacity: 1; }
-}
-.collaborators-overlay-cursor-highlighted .collaborators-overlay-user-cursor {
-	animation: collaborators-overlay-cursor-highlight 0.6s ease-in-out 3;
-}
-.collaborators-overlay-cursor-highlighted .collaborators-overlay-user-label {
-	animation: collaborators-overlay-label-highlight 0.6s ease-in-out 3;
-}
-@keyframes collaborators-overlay-cursor-highlight {
-	0%, 100% {
-		transform: scale(1);
-		filter: drop-shadow(0 0 0 transparent);
-	}
-	50% {
-		transform: scale(1.2);
-		filter: drop-shadow(0 0 8px currentColor);
-	}
-}
-@keyframes collaborators-overlay-label-highlight {
-	0%, 100% {
-		transform: translate(-11px, -100%) scale(1);
-		filter: drop-shadow(0 0 0 transparent);
-	}
-	50% {
-		transform: translate(-11px, -100%) scale(1.1);
-		filter: drop-shadow(0 0 6px currentColor);
-	}
-}
-.block-editor-block-list__block.is-collaborator-selected:not(:focus)::after {
-	content: "";
-	position: absolute;
-	pointer-events: none;
-	top: 0;
-	right: 0;
-	bottom: 0;
-	left: 0;
-	outline-color: var(--collaborator-outline-color);
-	outline-style: solid;
-	outline-width: calc(var(--wp-admin-border-width-focus) / var(--wp-block-editor-iframe-zoom-out-scale, 1));
-	outline-offset: calc(-1 * var(--wp-admin-border-width-focus) / var(--wp-block-editor-iframe-zoom-out-scale, 1));
-	box-shadow: inset 0 0 0 calc(var(--wp-admin-border-width-focus, 2px) + 1px) #fff, 0 0 0 1px #fff, ${ ELEVATION_X_SMALL };
-	z-index: 1;
-}
-@media (prefers-reduced-motion: reduce) {
-	.components-avatar.has-badge,
-	.components-avatar__name,
-	.collaborators-overlay-user-label,
-	.collaborators-overlay-user-cursor {
-		transition: none;
-		animation: none;
-	}
-}
-`;
+// 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;
 	postType: string | null;
+	cursorRegistry?: CursorRegistry;
 }
 
 /**
@@ -212,12 +33,14 @@ interface OverlayProps {
  * @param props.blockEditorDocument - The block editor document.
  * @param props.postId              - The ID of the post.
  * @param props.postType            - The type of the post.
+ * @param props.cursorRegistry      - The shared cursor registry.
  * @return The Overlay component.
  */
 export function Overlay( {
 	blockEditorDocument,
 	postId,
 	postType,
+	cursorRegistry,
 }: OverlayProps ) {
 	// Use state for the overlay element so that the hook re-runs once the ref is attached.
 	const [ overlayElement, setOverlayElement ] =
@@ -227,13 +50,46 @@ export function Overlay( {
 		overlayElement,
 		blockEditorDocument ?? null,
 		postId ?? null,
-		postType ?? null
+		postType ?? null,
+		RERENDER_DELAY_MS
+	);
+
+	const { highlights, rerenderHighlightsAfterDelay } = useBlockHighlighting(
+		overlayElement,
+		blockEditorDocument ?? null,
+		postId ?? null,
+		postType ?? null,
+		RERENDER_DELAY_MS
 	);
 
 	// Detect layout changes on overlay (e.g. turning on "Show Template") and window
-	// resizes, and re-render the cursors.
-	const resizeObserverRef = useResizeObserver( rerenderCursorsAfterDelay );
-	useEffect( rerenderCursorsAfterDelay, [ rerenderCursorsAfterDelay ] );
+	// resizes, and re-render the cursors and block highlights.
+	const onResize = useCallback( () => {
+		rerenderCursorsAfterDelay();
+		rerenderHighlightsAfterDelay();
+	}, [ rerenderCursorsAfterDelay, rerenderHighlightsAfterDelay ] );
+	const resizeObserverRef = useResizeObserver( onResize );
+
+	// Trigger the initial position computation on mount.
+	useEffect( () => {
+		const cleanupCursors = rerenderCursorsAfterDelay();
+		const cleanupHighlights = rerenderHighlightsAfterDelay();
+		return () => {
+			cleanupCursors();
+			cleanupHighlights();
+		};
+	}, [ 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 >( [
@@ -241,43 +97,109 @@ export function Overlay( {
 		resizeObserverRef,
 	] );
 
-	useBlockHighlighting(
-		blockEditorDocument ?? null,
-		postId ?? null,
-		postType ?? null
+	// Track cursor element refs for registry registration.
+	const cursorRefsMap = useRef< Map< number, HTMLElement > >( new Map() );
+
+	// Keep the registry in sync whenever the rendered cursors change.
+	useEffect( () => {
+		if ( ! cursorRegistry ) {
+			return;
+		}
+		const refs = cursorRefsMap.current;
+		const currentIds = new Set( cursors.map( ( c ) => c.clientId ) );
+
+		// Unregister cursors that are no longer rendered.
+		for ( const id of refs.keys() ) {
+			if ( ! currentIds.has( id ) ) {
+				cursorRegistry.unregisterCursor( id );
+				refs.delete( id );
+			}
+		}
+
+		// Register or update cursors that are currently rendered.
+		for ( const [ id, el ] of refs.entries() ) {
+			cursorRegistry.registerCursor( id, el );
+		}
+
+		return () => cursorRegistry.removeAll();
+	}, [ cursors, cursorRegistry ] );
+
+	// Callback ref factory to capture each cursor's DOM element.
+	const setCursorRef = useCallback(
+		( clientId: number ) => ( el: HTMLDivElement | null ) => {
+			if ( el ) {
+				cursorRefsMap.current.set( clientId, el );
+			} else {
+				cursorRefsMap.current.delete( clientId );
+			}
+		},
+		[]
 	);
 
 	// This is a full overlay that covers the entire iframe document. Good for
 	// scrollable elements like cursor indicators.
 	return (
 		<div className="collaborators-overlay-full" ref={ mergedRef }>
-			<style>{ COLLABORATORS_OVERLAY_STYLES }</style>
+			<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.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"
+						ref={ setCursorRef( cursor.clientId ) }
+						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"
-						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 ) => (
+				<Avatar
+					key={ highlight.blockId }
+					className="collaborators-overlay-block-label"
+					variant="badge"
+					size="small"
+					src={ highlight.avatarUrl }
+					name={ highlight.userName }
+					borderColor={ highlight.color }
+					style={ {
+						left: `${ highlight.x }px`,
+						top: `${ highlight.y }px`,
+					} }
+				/>
+			) ) }
 		</div>
 	);
 }