Suggest mode: Suggestion summary, attribute conflict detection, and architecture docs by adamsilverstein · Pull Request #78352 · WordPress/gutenberg

adamsilverstein · 2026-05-15T14:25:17Z

Overview

One of three replacement PRs for the now-closed #77407. This slice introduces the suggestion summary renderer, per-attribute conflict detection, snackbar feedback, and architecture documentation.

Tracking issue: #73411.

What's in this PR

Suggestion-mode component additions

suggestion-summary.js — Compact alternative to the full inline diff. Renders an Add / Delete / Format line per operation suitable for sidebar threads. Used by the collab-sidebar PR on top of this branch.
hasAttributeConflict + parseSuggestionPayload (provider) — Replaces the post-modified_gmt staleness compare with a per-attribute divergence check. modified_gmt flagged nearly every auto-saved suggestion as stale because every save bumps the post timestamp; the new check only prompts when the specific attributes a suggestion targets have moved off baseline.
with-suggestion-overlay and suggestion-diff refinements to match the new contract.

Editor store / UX

setEditorIntent snackbar — Mode transitions now surface a snackbar ("You're suggesting" / "You're editing" / "You're viewing") alongside the existing a11y announcement.
Store wiring — actions.js, reducer.js, selectors.js updated for the new selectors; use-block-editor-settings.js wires the suggestion provider settings through.
Style — suggestion-mode/style.scss is the home for suggestion visuals (block bracket marker, summary card); imported from packages/editor/src/style.scss.

Documentation

docs/explanations/architecture/suggestions.md — Architecture doc covering the provider abstraction, overlay subsystem, and lifecycle.
docs/reference-guides/data/data-core-editor.md — Updated to cover the new editor-store selectors / actions.

Tests

Unit: test/provider.js (extended), test/suggestion-summary.js (new), test/with-suggestion-overlay.js (extended).
e2e: suggestion-mode.spec.js updated to exercise the new flow.

Test plan

npm run test:unit -- packages/editor/src/components/suggestion-mode
npm run test:unit -- packages/editor/src/store/test/actions.js
npm run test:e2e -- test/e2e/specs/editor/various/suggestion-mode.spec.js
npm run lint:js -- packages/editor/src/components/suggestion-mode packages/editor/src/store

Manual:

Switch to Suggest mode → snackbar reads "You're suggesting".
Edit a paragraph → SuggestionSummary renders in the inline diff and (after the sidebar PR lands) in the note thread.
Submit, then in another window edit the same paragraph's attributes → reopening the original suggestion in the sidebar shows the staleness confirmation only when the specific attributes diverge — not on any unrelated post change.

Replaces part of #77407.

🗺️ PR Stack Navigation

#	PR	Phase
1	#77403 Intent scaffolding	Edit / Suggest / View mode
2	#77404 Overlay capture	In-memory suggestion overlay
3	#77405 Provider + Accept/Reject	`_wp_suggestion` meta, provider, sidebar actions
4	#77406 Summary + docs + attribute tests	Add/Delete/Formatting summary, architecture stub, conflict scoping
5a	#78351 REST permissions and PHP coverage	Permissions, payload cap, PHP tests
5b	#78352 Summary + attribute conflict + docs ← this PR	Renderer, per-attribute staleness, architecture docs
5c	#78353 Surface Apply/Reject in the collaboration sidebar	Icon buttons + e2e + sidebar wiring
6	#78308 Auto-save subsystem	Background debounced save (replaces commit-bar)

📋 Tracking issue: #73411

github-actions · 2026-05-15T14:25:32Z

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>

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

github-actions · 2026-05-18T17:02:53Z

Size Change: +1.36 kB (+0.02%)

Total Size: 7.51 MB

📦 View Changed

Filename	Size	Change
`build/scripts/editor/index.min.js`	481 kB	+219 B (+0.05%)
`build/styles/editor/style-rtl.css`	31 kB	+302 B (+0.98%)
`build/styles/editor/style-rtl.min.css`	26.4 kB	+267 B (+1.02%)
`build/styles/editor/style.css`	31.1 kB	+302 B (+0.98%)
`build/styles/editor/style.min.css`	26.4 kB	+269 B (+1.03%)

_{compressed-size-action}

github-actions · 2026-05-18T19:35:20Z

Flaky tests detected in df62560.
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/27780297253
📝 Reported issues:

[Flaky Test] The PHP version is rendered if the legacy attribute is true #78787 in /test/e2e/specs/editor/blocks/comments.spec.js

…and architecture docs Introduce SuggestionSummary as a compact alternative to the full inline diff, swap post-modified_gmt staleness for hasAttributeConflict (per-attribute divergence from the captured baseline), wire snackbar feedback into setEditorIntent transitions, and add the wp/suggestions architecture doc plus core/editor data-reference updates. Provider, with-suggestion-overlay, suggestion-diff, and the suggestion-mode e2e spec follow the new contract.

The suggest-mode stack diverged from trunk before #75147 landed, so addNoteIdToMetadata and getNoteIdsFromMetadata are absent from this branch's collab-sidebar/utils.js. suggestion-mode/provider.js imports both, breaking the JS bundle build (esbuild: no matching export) and cascading into the PHP, Playwright, and release checks. Vendor the two pure helpers verbatim from trunk (786c69c) so this PR builds independently of a full-stack rebase. They resolve cleanly against trunk's identical definitions when the stack is updated.

Three e2e tests asserted behavior not present on this branch; they were masked until the JS build break was fixed and the suite could run. editor-intent-switcher: the intent is session-scoped by design (see setEditorIntent / editorIntent reducer) - reload returns to Edit. Rewrite the reload test to assert that reset instead of expecting Suggest to persist, which the implementation deliberately refuses. suggestion-mode: 'auto-saves a content edit' and the heading-level capture test wait for an automatic debounced POST /wp/v2/comments. The debounced auto-save subsystem is Phase 6 (#78308), not in this stack's ancestry; here a suggestion is only persisted via the explicit commit-bar Submit button. Skip both with a tracking reference to #78308.

Commit d055691 vendored addNoteIdToMetadata/getNoteIdsFromMetadata onto this branch because the stale stack predated #75147. With trunk merged back into the stack, those helpers exist canonically in collab-sidebar/utils.js again, so the vendored copy is redundant and caused a duplicate-definition build break. Remove it; suggestion-mode provider.js now imports the trunk-supplied versions.

…e-5c-summary-diff-docs

Remove 17 vestigial bulk-suppression entries for files byte-identical to trunk (which carries no suppression for them), fixing the failing lint job.

…e-5c-summary-diff-docs

…e-5c-summary-diff-docs # Conflicts: # test/e2e/specs/editor/various/editor-intent-switcher.spec.js # tools/eslint/suppressions.json

adamsilverstein requested review from ajitbohra, fabiankaegy and juanmaguitar as code owners May 15, 2026 14:25

github-actions Bot added the [Package] Editor /packages/editor label May 15, 2026

adamsilverstein added [Status] In Progress Tracking issues with work in progress [Type] Feature New feature to highlight in changelogs. [Feature] Notes Phase 3 of the Gutenberg roadmap around block commenting labels May 15, 2026

adamsilverstein self-assigned this May 15, 2026

adamsilverstein requested review from Mamaduka and t-hamano and removed request for ajitbohra, fabiankaegy and juanmaguitar May 18, 2026 22:13

adamsilverstein mentioned this pull request May 18, 2026

Explore “Suggest mode" support for Notes #73411

Open

This was referenced Jun 6, 2026

Suggest mode: Combined feature branch (draft, for Playground testing) #78994

Draft

Notes iteration for WordPress 7.1 #76316

Open

adamsilverstein force-pushed the phase-5a-rest-backend branch from 95d4319 to 06c8368 Compare June 17, 2026 16:35

adamsilverstein requested review from manzoorwanijk and spacedmonkey as code owners June 17, 2026 16:35

adamsilverstein force-pushed the phase-5c-summary-diff-docs branch from 5920ff9 to 5dfa6f2 Compare June 17, 2026 16:35

github-actions Bot added the [Package] Editor /packages/editor label Jun 17, 2026

adamsilverstein force-pushed the phase-5a-rest-backend branch from 06c8368 to 1f7a652 Compare June 18, 2026 18:17

adamsilverstein added 4 commits June 18, 2026 20:18

adamsilverstein force-pushed the phase-5c-summary-diff-docs branch from 5dfa6f2 to df62560 Compare June 18, 2026 18:19

adamsilverstein added 6 commits June 20, 2026 01:48

Merge branch 'phase-5a-rest-backend' into phase-5c-summary-diff-docs

ccdd6f3

Merge remote-tracking branch 'origin/phase-5a-rest-backend' into phas…

9fda286

…e-5c-summary-diff-docs

Merge remote-tracking branch 'origin/phase-5a-rest-backend' into phas…

74e0398

…e-5c-summary-diff-docs

ESLint: prune stale suppressions on phase-5c

28df0ae

Remove 17 vestigial bulk-suppression entries for files byte-identical to trunk (which carries no suppression for them), fixing the failing lint job.

Merge remote-tracking branch 'origin/phase-5a-rest-backend' into phas…

74f19de

…e-5c-summary-diff-docs

Merge remote-tracking branch 'origin/phase-5a-rest-backend' into phas…

f6d5f8a

…e-5c-summary-diff-docs # Conflicts: # test/e2e/specs/editor/various/editor-intent-switcher.spec.js # tools/eslint/suppressions.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Suggest mode: Suggestion summary, attribute conflict detection, and architecture docs#78352

Suggest mode: Suggestion summary, attribute conflict detection, and architecture docs#78352
adamsilverstein wants to merge 10 commits into
phase-5a-rest-backendfrom
phase-5c-summary-diff-docs

adamsilverstein commented May 15, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 18, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 18, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

adamsilverstein commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

What's in this PR

Suggestion-mode component additions

Editor store / UX

Documentation

Tests

Test plan

🗺️ PR Stack Navigation

Uh oh!

github-actions Bot commented May 15, 2026

Uh oh!

github-actions Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

adamsilverstein commented May 15, 2026 •

edited

Loading

github-actions Bot commented May 18, 2026 •

edited

Loading

github-actions Bot commented May 18, 2026 •

edited

Loading