Repository navigation
Notes: Promote "Add note" to a dedicated block toolbar button - #78205
adamsilverstein wants to merge 32 commits into
Conversation
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
|
Size Change: -16 B (0%) Total Size: 7.91 MB 📦 View Changed
|
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.
|
Flaky tests detected in c47ab18. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/33440732507 should insert block with the slash inserter when using multiple words in
|
|
@jasmussen I gave your idea a spin here, let me know what you think! |
|
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 |
|
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? |
|
Well to me it feels like an improvement. |
|
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. |
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?
|
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.
t-hamano
left a comment
There was a problem hiding this comment.
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
|
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:
|
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. |
|
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. |
@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:
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! |
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
@jasmussen - I tried this out in #83460 One more option to consider: |
|
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 |
|
We should also consider the #83549.
|
|
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
|
Is this only within a certain mode, or always present on the block toolbar? |
…d-note-to-toolbar
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
|
Noting that here's a PR to remove the avatars: #83939 |
|
Noting also there's a PR here to remove the block alignments from paragraphs: #83945. |
|
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. |
|
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.
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?
PS: Apologies for long message 😅 |
…d-note-to-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
left a comment
There was a problem hiding this comment.
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.
| - 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)). |
There was a problem hiding this comment.
Let's consolidate these into a single entry.
| // 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; | ||
| } | ||
| } | ||
|
|
There was a problem hiding this comment.
I suspect this style is no longer needed, as it is already defined here:
gutenberg/packages/editor/src/components/collab-sidebar/style.scss
Lines 120 to 124 in 930a099
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. |






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
Add notetoolbar button appears (speech-bubble icon).NoteAvatarIndicatorcontinues to appear (participant avatars). Only one notes affordance is shown at a time, avoiding visual clutter.primaryAlt+M) → unchanged.Testing
Implementation
add-note-menu-item.js(MenuItem inNoteIconSlotFill) withadd-note-toolbar-button.js(ToolbarButton inNoteIconToolbarSlotFill).NoteIconSlotFillslot fromblock-settings-dropdownand unregister the private API.NotesSidebarto render the new toolbar button only when the selected block has no thread (mirrors the avatar-indicator branch).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)
NoteAvatarIndicatoralready handles the "open notes" affordance for threaded blocks.editor.notessupport, valid + registered, not classic).NoteAvatarIndicatorpattern).Screenshot
Test plan
primaryAlt+Mstill opens the new-note form.test/e2e/specs/editor/various/block-notes.spec.jsandtest/e2e/specs/editor/collaboration/collaboration-notes.spec.ts.Related
Summary by CodeRabbit
New Features
Bug Fixes
Tests