Skip to content

Notes: Promote "Add note" to a dedicated block toolbar button - #78205

Open
adamsilverstein wants to merge 32 commits into
trunkfrom
fix/78188-promote-add-note-to-toolbar
Open

adamsilverstein wants to merge 32 commits into
trunkfrom
fix/78188-promote-add-note-to-toolbar

Conversation

@adamsilverstein

@adamsilverstein adamsilverstein commented May 12, 2026 •

Copy link
Copy Markdown
Member

Summary

Closes #78188.

With Suggest mode making review notes effectively free (every edit becomes a note), the manual Add note action no longer belongs at the bottom of the block toolbar's overflow menu. This PR promotes it to a first-class toolbar button — a speech-bubble icon placed just before the ellipsis — so it sits at parity with Suggest mode's automatic note creation.

Behavior

  • Block with no thread → the new Add note toolbar button appears (speech-bubble icon).
  • Block with a thread → the existing NoteAvatarIndicator continues to appear (participant avatars). Only one notes affordance is shown at a time, avoiding visual clutter.
  • Distraction-free / view mode / unsupported post types → unchanged (no affordance).
  • Keyboard shortcut (primaryAlt+M) → unchanged.

Testing

Test in WordPress Playground

Implementation

  • Replace add-note-menu-item.js (MenuItem in NoteIconSlotFill) with add-note-toolbar-button.js (ToolbarButton in NoteIconToolbarSlotFill).
  • Remove the now-unused NoteIconSlotFill slot from block-settings-dropdown and unregister the private API.
  • Update NotesSidebar to render the new toolbar button only when the selected block has no thread (mirrors the avatar-indicator branch).
  • Update e2e specs (block-notes.spec.js, collaboration-notes.spec.ts) to click the toolbar button instead of opening the overflow menu.

Design decisions (from the issue's open questions)

  1. Zero notes vs. always: only render when block has zero notes — NoteAvatarIndicator already handles the "open notes" affordance for threaded blocks.
  2. Every block vs. opt-in: same gating as today's menu item (post-type editor.notes support, valid + registered, not classic).
  3. View mode: unchanged — entire sidebar is already hidden.
  4. Mobile/narrow: render in toolbar (matches existing NoteAvatarIndicator pattern).

Screenshot

image

Test plan

  • Insert a paragraph; confirm the speech-bubble Add note button appears in the block toolbar just before the ellipsis.
  • Click the button → New-note form opens and is focused.
  • Save a note → button is replaced by the avatar indicator on that block.
  • Insert a second paragraph (no note) → speech-bubble button appears again.
  • Toggle distraction-free mode → no Add note button surfaces.
  • Classic block → button is disabled with a "Convert to blocks to add notes." tooltip.
  • Keyboard shortcut primaryAlt+M still opens the new-note form.
  • Run test/e2e/specs/editor/various/block-notes.spec.js and test/e2e/specs/editor/collaboration/collaboration-notes.spec.ts.

Related

Summary by CodeRabbit

  • New Features

    • Added an accessible “Add note” button to the block toolbar.
    • The button now toggles the note form and updates its expanded state.
    • Added a fade-in transition for floating note cards, respecting reduced-motion preferences.
  • Bug Fixes

    • Improved note controls for editable blocks and distraction-free mode.
    • Updated keyboard navigation to include the “Add note” toolbar control.
  • Tests

    • Updated collaboration and block-note tests to use the toolbar button and verify toggle behavior.

Move the "Add note" action out of the block toolbar's More-options
overflow menu and render it as a first-class toolbar button (speech-bubble
icon) placed before the ellipsis. This raises the visibility of the
action now that Suggest mode makes individual notes a routine review
gesture rather than an edge-case affordance.

Render behavior: the new button only appears when the selected block has
no existing thread. When a thread exists, the existing NoteAvatarIndicator
continues to serve as the visible affordance for both viewing and adding
replies.

Implementation:
- Replace add-note-menu-item.js with add-note-toolbar-button.js,
  filling NoteIconToolbarSlotFill with a ToolbarButton instead of
  NoteIconSlotFill with a MenuItem.
- Remove the now-unused NoteIconSlotFill slot from block-settings-dropdown
  and unregister it from block-editor private APIs.
- Update the e2e specs to click the toolbar button instead of opening
  the block-settings dropdown.

Refs #78188
@adamsilverstein
adamsilverstein requested a review from ellatrix as a code owner May 12, 2026 15:38
@github-actions github-actions Bot added [Package] Editor /packages/editor [Package] Block editor /packages/block-editor labels May 12, 2026
@adamsilverstein adamsilverstein added [Status] In Progress Tracking issues with work in progress [Feature] Notes Phase 3 of the Gutenberg roadmap around block commenting labels May 12, 2026
@github-actions

github-actions Bot commented May 12, 2026 •

Copy link
Copy Markdown

Size Change: -16 B (0%)

Total Size: 7.91 MB

📦 View Changed
Filename Size Change
build/scripts/block-editor/index.min.js 478 kB -57 B (-0.01%)
build/scripts/editor/index.min.js 581 kB -17 B (0%)
build/styles/editor/style-rtl.css 31.6 kB +16 B (+0.05%)
build/styles/editor/style-rtl.min.css 27 kB +13 B (+0.05%)
build/styles/editor/style.css 31.6 kB +16 B (+0.05%)
build/styles/editor/style.min.css 27 kB +13 B (+0.05%)

compressed-size-action

@adamsilverstein adamsilverstein added the [Type] Feature New feature to highlight in changelogs. label May 12, 2026
The block toolbar now renders an 'Add note' button between 'More' and
'Options' (the ellipsis). Update the keyboard navigation walkthrough
to assert the new button appears in the expected tab sequence.
@github-actions

github-actions Bot commented May 12, 2026 •

Copy link
Copy Markdown

Flaky tests detected in c47ab18.
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/33440732507
📝 Reported tests:

should insert block with the slash inserter when using multiple words in /test/e2e/specs/editor/various/inserting-blocks.spec.js, passed after 1 failed attempt.
Error: apiRequestContext.fetch: socket hang up
Call log:
  - → GET http://localhost:8889/wp-json/wp/v2/blocks?per_page=100&status=publish%2Cfuture%2Cdraft%2Cpending%2Cprivate%2Ctrash
    - user-agent: Playwright/1.62.1 (x64; ubuntu 24.04) node/20.20 CI/1
    - accept: */*
    - accept-encoding: gzip,deflate,br
    - X-WP-Nonce: 0f73932059
    - cookie: wordpress_test_cookie=WP%20Cookie%20check; wordpress_logged_in_23778236db82f19306f247e20a353a99=admin%7C1788384279%7CKx5F6bIxDMEZ9hmZxsK9LPmj6wIvtGRtekLQ6H15koq%7C529f9345f2641f33308b0d49d8d39e2a871583914a2dae10a1adcb01b32dadc9; wp-settings-time-1=1788212609

    at RequestUtils.rest (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/rest.ts:112:39)
    at RequestUtils.deleteAllBlocks (/home/runner/work/gutenberg/gutenberg/packages/e2e-test-utils-playwright/src/request-utils/blocks.ts:23:28)
    at /home/runner/work/gutenberg/gutenberg/test/e2e/specs/editor/various/inserting-blocks.spec.js:11:22

@adamsilverstein

Copy link
Copy Markdown
Member Author

@jasmussen I gave your idea a spin here, let me know what you think!

@carolinan

carolinan commented May 13, 2026 •

Copy link
Copy Markdown
Contributor

I followed the test instructions and this is working well for me.

Note: The keyboard shortcut for adding a new note, Ctrl + Alt + M overrides the expected behavior when using a Swedish keyboard on Windows 11, it is expected to insert µ. But this shortcut was not introduced in this PR.

@jasmussen

Copy link
Copy Markdown
Contributor

Nice. How are you all feeling about this? I think there may be some visuals we can tweak over time, the precise icon and the placement of it, but IMO this feels like a decent thing to merge early for the 7.1 cycle so that we can test it as a new baseline. What do you think?

@carolinan

Copy link
Copy Markdown
Contributor

Well to me it feels like an improvement.

@Mamaduka

Copy link
Copy Markdown
Member

I think "Add note" was in the toolbar initially, but then was moved to the dropdown. It might be worth revisiting those old discussions.

Also, how is this going to work with #78223?

P.S. I see lots of overlapping issues/PRs; it would be nice to have a finalized spec. Otherwise, I think we will spend time on features that will be obsolete after a couple of iterations.

Comment thread packages/block-editor/CHANGELOG.md
@t-hamano

Copy link
Copy Markdown
Contributor
  • Block with a thread → the existing NoteAvatarIndicator continues to appear (participant avatars). Only one notes affordance is shown at a time, avoiding visual clutter.

There is #75147, which attempts to support multiple note threads per block. If both this PR and #75147 are shipped, the toolbar would look like this, correct?

image

@jasmussen

jasmussen commented May 13, 2026 •

Copy link
Copy Markdown
Contributor

I think "Add note" was in the toolbar initially, but then was moved to the dropdown. It might be worth revisiting those old discussions.

I was there for the discussion, and may even have been the one suggesting it move to the dropdown. The motivation from my perspective was always: we're shipping iteration 0 of this, and that's good, it lets us build the bicycle while riding it. But that in lacking inline comments, some management features, suggestions, multi user collaboration, the feature wasn't yet ready for prominence. By putting it in the dropdown, we reduced the surface area: yes you can use notes already! But it's intentionally de-emphasised while it continues to evolve between releases.

In suggesting now that we promite the action back, I'm also suggesting (kudos to you all), that probably now it is in fact ready for prominence. Time to shine!

Private APIs are not consumed externally, so the entry is unnecessary
per review feedback.
@adamsilverstein

adamsilverstein commented May 13, 2026 •

Copy link
Copy Markdown
Member Author

There is #75147, which attempts to support multiple note threads per block. If both this PR and #75147 are shipped, the toolbar would look like this, correct?

Yes, that looks right to me @t-hamano

@t-hamano t-hamano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

From a code perspective, it looks good. If it also looks good from a design perspective, I think we can ship this PR.

I think "Add note" was in the toolbar initially, but then was moved to the dropdown. It might be worth revisiting those old discussions.

In my investigation, I believe this menu was in the dropdown from the beginning.

…d-note-to-toolbar

# Conflicts:
#	packages/editor/CHANGELOG.md
#	packages/editor/src/components/collab-sidebar/index.js
#	test/e2e/specs/editor/various/block-notes.spec.js
@Mamaduka

Copy link
Copy Markdown
Member

I think this is making the button too prominent for a feature that might not be used 80% of users. The toolbar has limited space and is usually reserved for common actions.

cc @richtabor

@adamsilverstein

adamsilverstein commented Jun 15, 2026 •

Copy link
Copy Markdown
Member Author

I think this is making the button too prominent for a feature that might not be used 80% of users. The toolbar has limited space and is usually reserved for common actions.

cc @richtabor

Thanks for the feedback @Mamaduka - I don't feel strongly about this, it is primarily a UX/design question at this point. This PR is really an exploration so we can see how it feels having the notes button more prominently displayed.

I also experimented with a floating add note button next to text selections in #78223 which I personally found too obtrusive, but wanted to explore and share here for completeness.

The floating button is closest to what I see in Google docs, although we don't have any similar UI in Gutenberg as far as I can tell:

image

@fcoveram

fcoveram commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

I think this is making the button too prominent for a feature that might not be used 80% of users. The toolbar has limited space and is usually reserved for common actions.

I second this approach. And to me, this goes beyond the UX challenge.

The proposal is at the product level and involves user expectations around what tools are highlighted when editing a document. I still believe that edit modes is a worthy approach to accommodate affordances and tools depending on the user's intention. We are already doing that with pattern editing where controls are simplified to reduce friction.

In this case, the ongoing features related to notes outline the need for having a Comment mode where putting this action in the toolbar makes more sense.

@draganescu

Copy link
Copy Markdown
Contributor

In recent user testing I've seen the dot menu is much more attractive than we think - despite being a catch all to avoid visual clutter, the fact that it is a catch all actually trains users to 1st look there even for things that are available as buttons in the toolbar.

To be honest I don't know if the toolbar has today more value as significance of state in context (e.g. there are notes) rather than a quick access contextual UI. That is a long way of saying we may not want this button.

@adamsilverstein

adamsilverstein commented Sep 22, 2026 •

Copy link
Copy Markdown
Member Author

To be honest I don't know if the toolbar has today more value as significance of state in context (e.g. there are notes) rather than a quick access contextual UI. That is a long way of saying we may not want this button.

@draganescu - Thanks for the feedback and review! I am not at all attached to this approach am open to other ideas. A few points though:

  • We already use the block toolbar to show a view notes link (avatar icon(s)) when a block has existing notes:
image

Do you agree we have a discovery issue? If so, can you offer some ideas for how to make the feature more discoverable other than what the current PR proposes?

One other idea i explored is a floating tool similar to google docs:

Please review that one as well if you have a chance!

@jasmussen

Copy link
Copy Markdown
Contributor

We already use the block toolbar to show a view notes link (avatar icon(s)) when a block has existing notes:

Essentially this flow, going from empty paragraph to "noted" paragraph:

State

It's saying, if we already reserve that space when noted, maybe do it when un-noted too? Still, this is not a strong opinion from my end. What I would say is that if we don't add a notes button in the toolbar, we should add a notes icon to the ellipsis menu, and a shortcut key.

@adamsilverstein

Copy link
Copy Markdown
Member Author

What I would say is that if we don't add a notes button in the toolbar, we should add a notes icon to the ellipsis menu, and a shortcut key.

Thanks @jasmussen feedback noted. I'll work on a second PR with this approach for a comparison point. Ideally we would do real user testing on the two approaches (asking users to "add a note" and seeing how they interact); I'm sure we have time for that, but at least this will give us a "gut check" comparison of the two approaches.

…d-note-to-toolbar

# Conflicts:
#	packages/block-editor/CHANGELOG.md
#	packages/editor/CHANGELOG.md
@adamsilverstein

Copy link
Copy Markdown
Member Author

What I would say is that if we don't add a notes button in the toolbar, we should add a notes icon to the ellipsis menu, and a shortcut key.

@jasmussen - I tried this out in #83460

One more option to consider:

@annezazu

Copy link
Copy Markdown
Contributor

I like this much more than #78223. I confirmed the add note works both for overall notes and, when highlighting a specific part, to add a note just to that section. The only oddness is the View Notes linking to the very first note rather than the latest but I'm not sure if one is better than another:

Screen.Recording.2026-09-29.at.1.11.19.PM.mov

@fcoveram

Copy link
Copy Markdown
Contributor

Agree with @annezazu. This PR feels better than #78223, and the focus could be set on the latest comment.

@Mamaduka

Copy link
Copy Markdown
Member

We should also consider the #83549.

  • The last area of the toolbar will get crowded if we ship all the new items.
  • Close proximity to delete also increases the risk of accidental block removal.

@adamsilverstein

Copy link
Copy Markdown
Member Author

One other option that makes Notes a bit more discoverable without moving it out of the menu:

…d-note-to-toolbar

# Conflicts:
#	packages/editor/src/components/collab-sidebar/index.jsx
#	test/e2e/specs/editor/various/block-notes.spec.js
@richtabor

Copy link
Copy Markdown
Member

Is this only within a certain mode, or always present on the block toolbar?

adamsilverstein and others added 3 commits September 30, 2026 22:39
The trunk merge brought in its own Internal section under Unreleased,
leaving two headings that the changelog validator rejects.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CdtuWidg1XBK8cpYLNSWxF
The test added on trunk asserts no "Add …" button is in the block
toolbar, but this branch adds an "Add note" toolbar button that the
name-based locator also matches. Target the inserter class instead, as
the sibling test already does.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CdtuWidg1XBK8cpYLNSWxF
@jasmussen

Copy link
Copy Markdown
Contributor

Noting that here's a PR to remove the avatars: #83939

@jasmussen

Copy link
Copy Markdown
Contributor

Noting also there's a PR here to remove the block alignments from paragraphs: #83945.

@jasmussen

Copy link
Copy Markdown
Contributor

And here's an alternative to just removing the alignment from Paragraphs, removing it also from Quotes but bringing it into the inspector instead: #83955.

@yashjawale

Copy link
Copy Markdown
Contributor

In my opinion, having two buttons pertaining to a single feature (which is also slightly less used than the others) can make the toolbar a bit crowded.

image

I think the flow in #78205 (comment) might lead to less visual clutter. That way in both cases (notes already present/not) the primary notes action is present in the same location.

Adding a new note thread to a place where one already exists isn't a common action, and perhaps can go to three dot menus of toolbar (maybe also to three dot menu of threads, something like "start a new thread"?)

In Google Docs' case, whenever we click on a piece of text that already has a comment, it always highlights the existing thread so their toolbar button always starts a new thread. But since currently in our case clicking on a block doesn't bring out its thread too (since we have Inspector panel in that place), perhaps the primary action for notes button should be to focus on existing threads?

image

PS: Apologies for long message 😅

@annezazu

annezazu commented Oct 6, 2026

Copy link
Copy Markdown
Contributor

Is this only within a certain mode, or always present on the block toolbar?

@richtabor as is, this would be always present, which is part of the hesitancy in adding it outright. At the same time, discoverability and usability of this feature is pretty poor. Every single time you have to go to the three dot menu to add a new item. I lean towards removing both the + and delete item on the toolbar but including this PR to help with both aspects. Perhaps it only appears after a note has been added to ensure folks are using the feature first. This won't help with discoverability but perhaps that's a decent compromise.

…d-note-to-toolbar

# Conflicts:
#	packages/editor/CHANGELOG.md
#	packages/editor/src/components/collab-sidebar/index.jsx

@t-hamano t-hamano left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps it only appears after a note has been added to ensure folks are using the feature first.
It's saying, if we already reserve that space when noted, maybe do it when un-noted too? Still, this is not a strong opinion from my end.

Personally, I support these proposals.

Comment on lines +7 to +9
- Notes Sidebar: Promote the "Add note" action from the block-toolbar overflow menu to a dedicated toolbar button placed before the ellipsis. Blocks that already have a thread continue to show the avatar indicator alongside the button ([#78205](https://github.com/WordPress/gutenberg/pull/78205)).
- Notes Sidebar: The "Add note" toolbar button now toggles the form it opened and exposes `aria-expanded`, so clicking it again closes the form instead of silently doing nothing ([#78205](https://github.com/WordPress/gutenberg/pull/78205)).
- Notes Sidebar: Fade the floating note card in once its anchor has been measured, rather than cutting it to full opacity in a single frame ([#78205](https://github.com/WordPress/gutenberg/pull/78205)).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's consolidate these into a single entry.

Comment on lines +128 to +136
// The floating card renders at `opacity: 0` until `useFloatingBoard` has
// measured its anchor, so dropping that inline style is what reveals it.
// Fade across that step instead of hard-cutting the card into place.
.editor-collab-sidebar-panel__add-note.is-floating {
@media not (prefers-reduced-motion) {
transition: opacity 0.12s ease-out;
}
}

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suspect this style is no longer needed, as it is already defined here:

// Ease reflows, e.g. on selection change. The first positioning starts
// from `top: auto`, which doesn't animate.
@media (prefers-reduced-motion: no-preference) {
transition: top var(--wpds-motion-duration-md) var(--wpds-motion-easing-balanced);
}

@jasmussen

Copy link
Copy Markdown
Contributor

Perhaps it only appears after a note has been added to ensure folks are using the feature first.
It's saying, if we already reserve that space when noted, maybe do it when un-noted too? Still, this is not a strong opinion from my end.

I think it's compatible, but just connecting a dot with a parallel conversation in this PR that suggests replacing the user avatars with just the note button, having it do double duty.

@manzoorwanijk
manzoorwanijk removed their request for review October 7, 2026 06:44

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Feature] Notes Phase 3 of the Gutenberg roadmap around block commenting Needs Design Feedback Needs general design feedback. [Package] Block editor /packages/block-editor [Package] Editor /packages/editor [Status] In Progress Tracking issues with work in progress [Type] Feature New feature to highlight in changelogs.

Projects

Development

Successfully merging this pull request may close these issues.

Notes are hard to find: consider promoting "Add note" to the block toolbar