Notes: Render @ mentions as span chips and narrow the kses class allowance

[adamsilverstein]

Closes #80502.
Supersedes #80496 with the approach agreed in its discussion.

What

Switch the Notes @ mention markup from a link to a non-interactive span chip:

-<a class="wp-note-mention user-N" href="…">@Name</a>
+<span class="wp-note-mention user-N">@Name</span>

and replace the per-note kses arm/disarm machinery in lib/compat/wordpress-7.1/block-comments.php with two small always-on filters:

1. a wp_kses_allowed_html filter that allows span with class in the pre_comment_content context, and
2. a pre_comment_content filter at priority 11 (right after wp_filter_kses) that reduces every span's class to the only two tokens the mention markup uses: wp-note-mention and user-N.

Why

This lands the consensus from #80496:

• Mentions aren't links (@Mamaduka): they are tokens rendered as chips. Making them a span takes them out of the Link format UI entirely, which fixes the behavior in Mamaduka's screencast where editing a mention through the Link UI destroyed the mention markup. The wp-note-mention class stays so no registered format claims the element (formats are differentiated by tag name and class), and per Mamaduka's testing RichText preserves the unregistered span without a dedicated mention format.
• Keep classes, drop the data attribute (discussion): since the comment kses context requires an explicit allowance either way (data-* is not allowed by default in pre_comment_content, see the Notes: Carry mention user IDs in a data attribute instead of classes #80496 write-up), a data attribute has no security edge over a class whose tokens are strictly allowlisted. The class also keeps working as the format-differentiation and styling hook.
• Close the open-class hole without stateful kses arming (@westonruter's original concern): the previous approach allowed any class on note links, guarded by ~120 lines of per-write arm/disarm across two request paths. Now the allowance is unconditional but reduced to exactly two inert tokens, so there is no styling/scripting selector surface to protect and no kses state to arm and disarm.

Behavior change

All commenters (including anonymous ones) can now persist <span> elements whose class is limited to wp-note-mention and/or user-N in comment content. This is inert: span is semantics-free, the two tokens are not styling or scripting hooks outside the notes sidebar, and mention notification parsing (#79606) only processes note-type comments.

The class reduction only runs while the restrictive comment allowlist (wp_filter_kses) is active: users with unfiltered_html are filtered through wp_filter_post_kses, where arbitrary classes are already permitted, and narrowing their markup would restrict what core allows them to post.

Coordination follow-ups

• Gutenberg Notify mentioned users and thread followers in Notes #79606 (mention notifications): the PHP parser should match mention spans rather than anchors (the user-N class parsing itself is unchanged), and per Mamaduka's last review note it should add an identity check before notifying - the chip text can be partially edited while the span retains its user-N class, so the parser should verify the remaining text still matches the mentioned user before emailing.
• wordpress-develop Comments: Allow the Notes @mention chip markup in comment content (kses) wordpress-develop#12503: reduces to the same two filters in core, at which point the function_exists( '_wp_kses_allow_note_mention_span' ) guard here disables this plugin copy.

Testing instructions

1. As a user without unfiltered_html (e.g. an author), open a post, select a block, and add a note.
2. Type @ and pick a teammate. The mention renders as a chip.
3. Save the note. The chip survives the round-trip as <span class="wp-note-mention user-<id>"> (inspect the element). This is the case the kses allowance exists for.
4. Place the caret inside a saved mention: no Link format popover appears, and editing surrounding text leaves the chip intact.

Automated coverage:

• PHP: phpunit/tests/notes-mention-kses-test.php
• e2e: the Mentions in the note form describe in test/e2e/specs/editor/various/block-notes.spec.js

[github-actions]

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: adamsilverstein <adamsilverstein@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>

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

[github-actions]

Size Change: -532 B (-0.01%)

Total Size: 7.75 MB

📦 View Changed

Filename	Size	Change
build/scripts/block-editor/index.min.js	427 kB	-10 B (0%)
build/scripts/block-library/index.min.js	354 kB	-46 B (-0.01%)
build/scripts/editor/index.min.js	500 kB	-79 B (-0.02%)
build/styles/editor/style-rtl.css	31.2 kB	-108 B (-0.35%)
build/styles/editor/style-rtl.min.css	26.5 kB	-91 B (-0.34%)
build/styles/editor/style.css	31.2 kB	-107 B (-0.34%)
build/styles/editor/style.min.css	26.5 kB	-91 B (-0.34%)

_{compressed-size-action}

[Mamaduka]

Thanks, @adamsilverstein!

The client-side code looks good, and mentions are testing well for me.

@westonruter, might have more feedback regarding the PHP-side, but here's one thing I noticed.

The gutenberg_notes_sanitize_mention_classes could use HTML APIs class_list, add_class and remove_class methods.

[adamsilverstein]

here's one thing I noticed.

The gutenberg_notes_sanitize_mention_classes could use HTML APIs class_list, add_class and remove_class methods.

Good suggestion, I'll work on it.

[adamsilverstein]

Thanks for the review and testing! Switched to class_list() / remove_class() in 2f1ee39 - remove_class() already drops the class attribute when the last token goes, so the manual attribute handling collapsed to a single loop.

[t-hamano]

Note that starting on the 22nd at around 9:00 UTC tomorrow, I plan to release Gutenberg 23.6 RC3, followed by the official release, and then synchronize core and Gutenberg. If we intend to ship this PR to WP 7.1 Beta3 and Gutenberg 23.6, it should be fine as long as this PR is merged by then.

[westonruter]

One more passing thought here: what about using a custom element? There could be a wp-user-mention tag: <wp-user-mention data-id="N">@Name</wp-user-mention>. This would further constrain the markup to just the intended usage. Just a thought, not firmly held.

[github-actions]

Flaky tests detected in ff3e2c6.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/29850844616
📝 Reported issues:

• [Flaky Test] As a user I want to be able to add multiple close buttons so that users can close the overlay from different positions #79925 in /test/e2e/specs/site-editor/navigation-overlay-template-part.spec.js

[Mamaduka]

One more passing thought here: what about using a custom element? There could be a wp-user-mention tag: <wp-user-mention data-id="N">@Name</wp-user-mention>. This would further constrain the markup to just the intended usage. Just a thought, not firmly held.

Probably easier to deal with native elements at this point. Then there's React's handling of custom elements to consider, which just added better support in React 19, and it's not shipping until next release

[westonruter]

Assuming this is synchronized with the latest from the core PR.

[github-actions]

I just cherry-picked this PR to the wp/7.1 branch to get it included in the next release: fa3ebec

[t-hamano]

I just cherry-picked this PR to the release/23.6 branch to get it included in the next release: 15f9943

[adamsilverstein]

Just noting I didn't manage to hit the cutoff to commit the PHP backport PR - WordPress/wordpress-develop#12503 for Beta 3, so the kses change won't land in core until Beta 4. I'll commit it as soon as Beta 3 release is complete.