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

package/src/components/collaborators-overlay/cursor-dom-utils.ts

@@ -0,0 +1,382 @@
+export interface SelectionRect {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+
+export interface CursorCoords {
+	x: number;
+	y: number;
+	height: number;
+}
+
+const MAX_NODE_OFFSET_COUNT = 500;
+
+/**
+ * Given a selection, returns the coordinates of the cursor in the block.
+ *
+ * @param absolutePositionIndex - The absolute position index
+ * @param blockElement          - The block element (or null if deleted)
+ * @param editorDocument        - The editor document
+ * @param overlayRect           - Pre-computed bounding rect of the overlay element
+ * @return The position of the cursor
+ */
+export const getCursorPosition = (
+	absolutePositionIndex: number | null,
+	blockElement: HTMLElement | null,
+	editorDocument: Document,
+	overlayRect: DOMRect
+): CursorCoords | null => {
+	if ( absolutePositionIndex === null || ! blockElement ) {
+		return null;
+	}
+
+	return (
+		getOffsetPositionInBlock(
+			blockElement,
+			absolutePositionIndex,
+			editorDocument,
+			overlayRect
+		) ?? 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 overlayRect    - Pre-computed bounding rect of the overlay element
+ * @return The position of the cursor
+ */
+const getOffsetPositionInBlock = (
+	blockElement: HTMLElement,
+	charOffset: number,
+	editorDocument: Document,
+	overlayRect: DOMRect
+) => {
+	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 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,
+	};
+};
+
+/**
+ * Computes selection highlight rectangles for a text range within a single block.
+ *
+ * @param blockElement   - The block element
+ * @param startOffset    - Start character offset within the block
+ * @param endOffset      - End character offset within the block
+ * @param editorDocument - The editor document
+ * @param overlayRect    - Pre-computed bounding rect of the overlay element
+ * @return Array of selection rectangles relative to the overlay, or null on failure
+ */
+export const getSelectionRects = (
+	blockElement: HTMLElement,
+	startOffset: number,
+	endOffset: number,
+	editorDocument: Document,
+	overlayRect: DOMRect
+): SelectionRect[] | null => {
+	// Normalize direction.
+	let normalizedStart = startOffset;
+	let normalizedEnd = endOffset;
+	if ( normalizedStart > normalizedEnd ) {
+		[ normalizedStart, normalizedEnd ] = [ normalizedEnd, normalizedStart ];
+	}
+
+	const startPos = findInnerBlockOffset(
+		blockElement,
+		normalizedStart,
+		editorDocument
+	);
+	const endPos = findInnerBlockOffset(
+		blockElement,
+		normalizedEnd,
+		editorDocument
+	);
+
+	const range = editorDocument.createRange();
+	try {
+		range.setStart( startPos.node, startPos.offset );
+		range.setEnd( endPos.node, endPos.offset );
+	} catch {
+		return null;
+	}
+
+	const clientRects = range.getClientRects();
+	const rects: SelectionRect[] = [];
+
+	for ( const rect of clientRects ) {
+		if ( rect.width === 0 && rect.height === 0 ) {
+			continue;
+		}
+		const x = rect.left - overlayRect.left;
+		const y = rect.top - overlayRect.top;
+
+		// Range.getClientRects() can return duplicate rects at inline
+		// formatting boundaries (e.g. <em>, <strong>). Skip exact matches.
+		const isDuplicate = rects.some(
+			( r ) =>
+				r.x === x &&
+				r.y === y &&
+				r.width === rect.width &&
+				r.height === rect.height
+		);
+		if ( isDuplicate ) {
+			continue;
+		}
+
+		rects.push( {
+			x,
+			y,
+			width: rect.width,
+			height: rect.height,
+		} );
+	}
+
+	return rects.length > 0 ? rects : null;
+};
+
+/**
+ * Computes selection highlight rectangles for the full content of a block.
+ * Used for intermediate blocks in a multi-block selection.
+ *
+ * @param blockElement   - The block element
+ * @param editorDocument - The editor document
+ * @param overlayRect    - Pre-computed bounding rect of the overlay element
+ * @return Array of selection rectangles relative to the overlay
+ */
+export const getFullBlockSelectionRects = (
+	blockElement: HTMLElement,
+	editorDocument: Document,
+	overlayRect: DOMRect
+): SelectionRect[] => {
+	const range = editorDocument.createRange();
+	range.selectNodeContents( blockElement );
+	const clientRects = range.getClientRects();
+	const rects: SelectionRect[] = [];
+
+	for ( const rect of clientRects ) {
+		if ( rect.width === 0 && rect.height === 0 ) {
+			continue;
+		}
+		rects.push( {
+			x: rect.left - overlayRect.left,
+			y: rect.top - overlayRect.top,
+			width: rect.width,
+			height: rect.height,
+		} );
+	}
+
+	// Fallback: if getClientRects returned nothing, use the block's bounding rect.
+	if ( rects.length === 0 ) {
+		const blockRect = blockElement.getBoundingClientRect();
+		if ( blockRect.width > 0 && blockRect.height > 0 ) {
+			rects.push( {
+				x: blockRect.left - overlayRect.left,
+				y: blockRect.top - overlayRect.top,
+				width: blockRect.width,
+				height: blockRect.height,
+			} );
+		}
+	}
+
+	return rects;
+};
+
+/**
+ * Finds all block elements between two blocks in DOM order (exclusive of start and end).
+ *
+ * @param startBlockId   - The clientId of the start block
+ * @param endBlockId     - The clientId of the end block
+ * @param editorDocument - The editor document
+ * @return Array of intermediate block HTMLElements in document order
+ */
+export const getBlocksBetween = (
+	startBlockId: string,
+	endBlockId: string,
+	editorDocument: Document
+): HTMLElement[] => {
+	const allBlocks =
+		editorDocument.querySelectorAll< HTMLElement >( '[data-block]' );
+
+	let startIndex = -1;
+	let endIndex = -1;
+
+	for ( let i = 0; i < allBlocks.length; i++ ) {
+		const blockId = allBlocks[ i ].getAttribute( 'data-block' );
+		if ( blockId === startBlockId ) {
+			startIndex = i;
+		}
+		if ( blockId === endBlockId ) {
+			endIndex = i;
+		}
+	}
+
+	if ( startIndex === -1 || endIndex === -1 ) {
+		return [];
+	}
+
+	// Normalize order.
+	if ( startIndex > endIndex ) {
+		[ startIndex, endIndex ] = [ endIndex, startIndex ];
+	}
+
+	const result: HTMLElement[] = [];
+	for ( let i = startIndex + 1; i < endIndex; i++ ) {
+		result.push( allBlocks[ i ] );
+	}
+	return result;
+};
+
+/**
+ * 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
+ */
+export 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 };
+};
+
+/**
+ * Check if node `a` precedes node `b` in document order.
+ *
+ * @param a - First node.
+ * @param b - Second node.
+ * @return True if `a` comes before `b`.
+ */
+export const isNodeBefore = ( a: Node, b: Node ): boolean =>
+	a.compareDocumentPosition( b ) === Node.DOCUMENT_POSITION_FOLLOWING;

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