Block Comments: Highlight the related block by karthick-murugan · Pull Request #71308 · WordPress/gutenberg

karthick-murugan · 2025-08-22T12:25:40Z

What?

This PR introduces a visual highlight for the related block when a comment is selected in the sidebar. It ensures that users can quickly identify which block a comment is associated with inside the editor.

Why?

Currently, when comments are shown in the sidebar, there is no clear indication in the canvas of which block they belong to. This creates confusion and slows down workflows for authors and reviewers.

By highlighting the related block whenever its associated comment is selected, users will have a clear visual indicator of context, improving the overall commenting experience.

How?

When a comment is selected:

The related block is programmatically selected and a temporary data-comment-highlight="true" attribute is applied to the block’s DOM element inside the editor iframe.

A CSS rule applies a subtle highlight style to the block (e.g., outline or background fade).

When the comment is deselected or another block/comment is selected:

The data-comment-highlight attribute is removed, restoring the block to its normal appearance.

Implementation details

Uses iframe.contentDocument.querySelector('[data-block="..."]') to locate the block.

Adds data-comment-highlight="true" instead of class manipulation, since class selectors weren’t applying reliably inside the editor iframe.

Adds scoped CSS targeting [data-comment-highlight="true"] to visually differentiate highlighted blocks.

Testing Instructions

Open a post or page in the block editor.

Add a few blocks and insert comments linked to those blocks.

From the sidebar, click on a comment.

✅ The related block in the editor should receive a visible highlight.

Screenshot/ Video

REC-20250822175358.mp4

This reverts commit 63f81c1.

github-actions · 2025-08-22T12:25:51Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: karthick-murugan <[email protected]>
Co-authored-by: t-hamano <[email protected]>
Co-authored-by: adamsilverstein <[email protected]>
Co-authored-by: Mamaduka <[email protected]>
Co-authored-by: joedolson <[email protected]>
Co-authored-by: Sahil1617 <[email protected]>
Co-authored-by: joemcgill <[email protected]>
Co-authored-by: jeffpaul <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

adamsilverstein · 2025-08-22T17:56:08Z

packages/editor/src/components/collab-sidebar/comments.js

+			selectBlock( relatedBlocks[ 0 ] );
+
+			const iframe = document.querySelector(
+				'iframe[name="editor-canvas"]'


selecting and manipulating elements in the DOM this way feels fragile. Did you explore using a block attribute / datastore to tie the comment to the block/highlighting?

Perhaps we could leverage the existing mechanism that ties between blocks and comments - clicking on a block highlights the related comment thread?

@adamsilverstein - Updated the feedback.

REC-20250826195838.mp4

t-hamano · 2025-09-19T06:28:42Z

I’ve adjusted the flash timing so the effect is more noticeable.

Since flashBlock is a public API, I would recommend not changing the API in this PR, and I think it should be considered in a follow-up.

karthick-murugan · 2025-09-19T06:32:00Z

I’ve adjusted the flash timing so the effect is more noticeable.

Since flashBlock is a public API, I would recommend not changing the API in this PR, and I think it should be considered in a follow-up.

Got it @t-hamano. I will create a new issue and a PR for the flashBlock API changes. Also will remove the changes from this PR. Thank you.

Mamaduka

Left a couple more notes. I think we're close to finishing this.

Mamaduka · 2025-09-19T07:39:10Z

packages/editor/src/components/collab-sidebar/comments.js

+	const [ focusThread, setFocusThread ] = useState(
+		showCommentBoard && blockCommentId ? blockCommentId : null
+	);
+
+	// Sync comment ↔ block highlighting bidirectionally.
+	useEffect( () => {
+		// Highlight comment when block is selected.
+		if ( blockCommentId && ! focusThread ) {
+			setFocusThread( blockCommentId );
+		}
+	}, [ blockCommentId, focusThread, blocks, setFocusThread ] );


Similar sync effects can be tricky. I know there are "checks" in place, but this effect will run a lot of times. Each block update will trigger the effect.

IMO, we have a clear use, even "click on a comment element", there should be no need for any side-effects. Technically, we should be able to house all required logic in handleCommentSelect.

@Mamaduka – Removing the useEffect will stop highlighting comments when any block is selected, but the block flashing when a comment is selected will continue to work as expected. Do you think it’s fine if I proceed with this approach?

It's not a big blocker; we can start here and refactor later.

I just noticed that the blocks dependency isn't required for this effect; what was the reason for adding it?

Its just for syncing the highlight.

Seems like an odd hack.

Mamaduka · 2025-09-19T07:41:26Z

packages/editor/src/components/collab-sidebar/comments.js

+	// Handle comment selection.
+	const handleCommentSelect = useCallback(
+		( threadId ) => {
+			// Clear the add comment form when selecting a comment.
+			setShowCommentBoard( false );
+
+			// Set the focused thread.
+			setFocusThread( threadId );
+
+			// Flash the related block when a comment is clicked.
+			if ( blocks ) {
+				const relatedBlockClientId = findBlockByCommentId(
+					threadId,
+					blocks
+				);
+				if ( relatedBlockClientId ) {
+					flashBlock( relatedBlockClientId );
+				}
+			}
+		},
+		[ blocks, flashBlock, setFocusThread, setShowCommentBoard ]
+	);


Why do we need two handleCommentSelect functions? The logic should be co-located in a single callback below.

P.S. Memoization is sort of useless here. The blocks dependency will often change.

@Mamaduka - Updated both the changes.

Sorry, I should've been clearer. What I was suggesting was moving all the logic into handleCommentSelect defined in the Thread component.

@Mamaduka - Thanks for the clarification! I've moved all the logic into the handleCommentSelect function defined in the Thread component as you suggested.

Changes made:
✅ Removed the handleCommentSelect function from the main Comments component
✅ Consolidated all logic (clearing comment board, setting focus, flashing blocks, scrolling) into the single handleCommentSelect in the Thread component
✅ Removed the useEffect for comment ↔ block highlighting sync
✅ Removed unnecessary useCallback memoization

The code is now much cleaner with a single source of truth for comment selection logic, and no performance issues from the frequently changing blocks dependency in memoization.

Mamaduka · 2025-09-19T09:34:57Z

packages/editor/src/components/collab-sidebar/comments.js

+		// Flash the related block when a comment is clicked.
+		if ( blocks ) {
+			const relatedBlockClientId = findBlockByCommentId(
+				threadId,
+				blocks
+			);
+			if ( relatedBlockClientId ) {
+				// Use longer timeout for comment-to-block highlighting (800ms)
+				flashBlock( relatedBlockClientId, 800 );
+			}
+		}


We can just use the relatedBlock value here. There's no need to find the same value twice.

@Mamaduka - Yes done.

Mamaduka · 2025-09-19T09:37:11Z

packages/editor/src/components/collab-sidebar/comments.js

-	// Sync comment ↔ block highlighting bidirectionally.
-	useEffect( () => {
-		// Highlight comment when block is selected.
-		if ( blockCommentId && ! focusThread ) {
-			setFocusThread( blockCommentId );
-		}
-	}, [ blockCommentId, focusThread, blocks, setFocusThread ] );


I thought we were keeping this effect for now? Was the removal intentional?

Sorry, just saw this mentioned in #71308 (comment). But it's still not clear if the removal was intentional.

Related: #71308 (comment)

@Mamaduka - Not intentional. Added back.

Mamaduka · 2025-09-19T10:01:57Z

packages/editor/src/components/collab-sidebar/comments.js

+		// Flash the related block when a comment is clicked.
+		if ( relatedBlock ) {
+			flashBlock( relatedBlock );
+		}
+
+		// Scroll to the related block element if available.
+		if ( relatedBlock && relatedBlockElement ) {
+			relatedBlockElement.scrollIntoView( {
+				behavior: 'instant',
+				block: 'center',
+			} );
+		}


Maybe we should combine these so that they can "flash" the block highlight after the scroll.

P.S. Most of the inline comments inside the handleCommentSelect function aren't needed, IMO. What each part of the code is doing is clear.

@Mamaduka - Good point! I've combined the flash and scroll so the block highlights after scrolling, and remove the unnecessary inline comments since the code is self-explanatory. Thank You.

t-hamano

LGTM! Thank you so much for sticking with it until the end. I believe this is the best we can do for now. If necessary, let's follow up by removing unnecessary effects, improving performance, and refactoring.

adamsilverstein · 2025-09-19T16:58:28Z

Nice work here @karthick-murugan - thanks for sticking with this thru all the feedback (and thanks @t-hamano and @Mamaduka for all the helpful guidance), this was a tricky issue to get working well.

* Image size fix in lightbox * Revert "Image size fix in lightbox" This reverts commit 63f81c1. * Highlight and scroll to related blocks * Feedback changes updated * Latest Feedback updated * Feedback changes updated * Feedback changes added * Feedback changes * Feedback changes * Remove unecessarunnecessary effect and new api * Fixed feedback issues * Added flashblock and updated highlight issues * Update packages/editor/src/components/collab-sidebar/comments.js Co-authored-by: Adam Silverstein <[email protected]> * Feedback changes * Feedback changes updated * Update packages/editor/src/components/collab-sidebar/comments.js Co-authored-by: Adam Silverstein <[email protected]> * Flashblock and scroll updates added * Removing FlashBlock API changes * Remove duplicate handleCommentSelect * handleCommentSelect to Thread Component * Updating feedback * FlashBlock after scroll --------- Co-authored-by: karthick-murugan <[email protected]> Co-authored-by: t-hamano <[email protected]> Co-authored-by: adamsilverstein <[email protected]> Co-authored-by: Mamaduka <[email protected]> Co-authored-by: joedolson <[email protected]> Co-authored-by: Sahil1617 <[email protected]> Co-authored-by: joemcgill <[email protected]> Co-authored-by: jeffpaul <[email protected]>

karthick-murugan and others added 27 commits December 3, 2024 19:25

Image size fix in lightbox

63f81c1

Revert "Image size fix in lightbox"

0e19583

This reverts commit 63f81c1.

Merge branch 'WordPress:trunk' into trunk

f226ae0

Merge branch 'WordPress:trunk' into trunk

d074ba9

Merge branch 'WordPress:trunk' into trunk

4d847ca

Merge branch 'WordPress:trunk' into trunk

c9115b2

Merge branch 'WordPress:trunk' into trunk

b81e6ff

Merge branch 'WordPress:trunk' into trunk

efe57e5

Merge branch 'WordPress:trunk' into trunk

228e924

Merge branch 'WordPress:trunk' into trunk

c448a21

Merge branch 'WordPress:trunk' into trunk

05bb54c

Merge branch 'WordPress:trunk' into trunk

619fed3

Merge branch 'WordPress:trunk' into trunk

301d70f

Merge branch 'WordPress:trunk' into trunk

c80640f

Merge branch 'WordPress:trunk' into trunk

6ed9ff3

Merge branch 'WordPress:trunk' into trunk

09b4cf2

Merge branch 'WordPress:trunk' into trunk

27e4bbc

Merge branch 'WordPress:trunk' into trunk

52f809e

Merge branch 'WordPress:trunk' into trunk

e7679f1

Merge branch 'WordPress:trunk' into trunk

190b44e

Merge branch 'WordPress:trunk' into trunk

26aafe7

Merge branch 'WordPress:trunk' into trunk

fe1916c

Merge branch 'WordPress:trunk' into trunk

58dddf5

Merge branch 'WordPress:trunk' into trunk

ff6f5e1

Merge branch 'WordPress:trunk' into trunk

c239ca4

Merge branch 'WordPress:trunk' into trunk

0bb4101

Highlight and scroll to related blocks

ed989ae

karthick-murugan requested a review from ellatrix as a code owner August 22, 2025 12:25

adamsilverstein reviewed Aug 22, 2025

View reviewed changes

Removing FlashBlock API changes

5ad606b

karthick-murugan mentioned this pull request Sep 19, 2025

Make flashBlock duration configurable #71751

Closed

Mamaduka reviewed Sep 19, 2025

View reviewed changes

karthick-murugan added 2 commits September 19, 2025 14:27

Remove duplicate handleCommentSelect

b8c00d3

handleCommentSelect to Thread Component

327b7a4

Mamaduka reviewed Sep 19, 2025

View reviewed changes

Updating feedback

12a15a2

Mamaduka reviewed Sep 19, 2025

View reviewed changes

FlashBlock after scroll

f4619ab

Mamaduka requested review from adamsilverstein and t-hamano September 19, 2025 10:11

Mamaduka added the [Type] Enhancement A suggestion for improvement. label Sep 19, 2025

t-hamano approved these changes Sep 19, 2025

View reviewed changes

Mamaduka changed the title ~~Highlight Related Block~~ Block Comments: Highlight the related block Sep 19, 2025

t-hamano merged commit d6210ac into WordPress:trunk Sep 19, 2025
73 of 75 checks passed

github-project-automation bot moved this from 🔎 Needs Review to ✅ Done in WordPress 6.9 Editor Tasks Sep 19, 2025

github-actions bot added this to the Gutenberg 21.8 milestone Sep 19, 2025

karthick-murugan deleted the highlight-related-block branch September 19, 2025 12:20

t-hamano mentioned this pull request Sep 22, 2025

Block Comments Accessibility: Options button is focused, Some element in the sidebar should be focused #71676

Closed

6 tasks

Mamaduka mentioned this pull request Sep 24, 2025

Block Comments: Fix canceling the form for a selected block #71862

Merged

This was referenced Sep 25, 2025

Block Comments: Improve input labels #71843

Merged

Block Comment: Improve related block highlighting #71932

Merged

t-hamano added [Feature] Notes Phase 3 of the Gutenberg roadmap around block commenting and removed Collaborative Workflows Phase 3 of the Gutenberg roadmap around all-things related to collaborative workflows labels Oct 4, 2025

t-hamano mentioned this pull request Oct 5, 2025

Block Comments: Select block when comment is selected #72082

Merged

Conversation

karthick-murugan commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-hamano commented Sep 19, 2025

Uh oh!

karthick-murugan commented Sep 19, 2025

Uh oh!

Mamaduka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Mamaduka Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-hamano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

adamsilverstein commented Sep 19, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

karthick-murugan commented Aug 22, 2025 •

edited

Loading

github-actions bot commented Aug 22, 2025 •

edited

Loading

Mamaduka Sep 19, 2025 •

edited

Loading