Phase 4: Attribute suggestions, architecture docs, e2e coverage#77406
Draft
adamsilverstein wants to merge 1 commit intosuggest-mode-phase-3from
Draft
Phase 4: Attribute suggestions, architecture docs, e2e coverage#77406adamsilverstein wants to merge 1 commit intosuggest-mode-phase-3from
adamsilverstein wants to merge 1 commit intosuggest-mode-phase-3from
Conversation
adamsilverstein
changed the title
This was referenced Apr 16, 2026
|
Size Change: 0 B Total Size: 7.75 MB ℹ️ View Unchanged
|
adamsilverstein
force-pushed
the
suggest-mode-phase-3
branch
from
3f85774 to
7e2fe59
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-4
branch
2 times, most recently
from
37bd62c to
8111615
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-3
branch
2 times, most recently
from
9debb13 to
f63fe8c
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-4
branch
from
8111615 to
7368e91
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-3
branch
from
f63fe8c to
66f2542
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-4
branch
from
7368e91 to
e6e6960
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-3
branch
from
66f2542 to
5f968da
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-4
branch
from
e6e6960 to
2a1c564
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-3
branch
from
5f968da to
8e41010
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-4
branch
from
2a1c564 to
1a1f57b
Compare
adamsilverstein
force-pushed
the
suggest-mode-phase-3
branch
from
8e41010 to
31a0ce8
Compare
Phase 4 of the Suggest mode effort. The attribute-set operation type already handles all block attributes generically (text, heading level, alignment, style objects), so this phase focuses on verification, documentation, and hardening. New: - E2E test proving non-text attribute suggestions work end-to-end (heading level change via toolbar in Suggest mode). - Architecture doc at docs/explanations/architecture/suggestions.md covering the overlay, payload schema, provider interface, apply/ reject lifecycle, diff rendering, Yjs v2 migration path, and known limitations (structural suggestions, inline selections, permissions, rich-text format fidelity). Known limitation documented: applying another user's suggestion requires moderate_comments because core's update_item_permissions_check gates on edit_comment. A follow-up PR should override this for notes. Refs #73411
adamsilverstein
force-pushed
the
suggest-mode-phase-4
branch
from
1a1f57b to
306e967
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
This is one of 5 stacked PRs implementing Suggest mode for the WordPress editor — a Google Docs–style workflow where reviewers can propose changes that the post author can Accept or Reject. Tracked in #73411, with design direction from #73410 and jasmussen's mockups.
Architecture & Yjs readiness
The eventual long-term storage primitive for suggestions is the Yjs
AttributionManagerarriving in Yjs v14 (PR #77005), which attributes CRDT document changes to specific clients — exactly what suggested edits need. However, Yjs v14 is pre-release with an unstable API, and even with Yjs, server-side persistence is still needed for non-RTC users.Rather than block on Yjs, this series builds the full feature now with a comment-meta backend behind a swappable
SuggestionsProviderinterface shaped to match Yjs attribution semantics:attribute-set) — not HTML diffs — so they map directly to whatAttributionManagerwould emit.createSuggestion,updateSuggestion,deleteSuggestion,applySuggestion,rejectSuggestion. Today's implementation reads/writes comment meta; a futureyjs-provider.jscan drop in with the same methods.When #77005 stabilizes, the migration is: implement
yjs-provider.jsagainst the same interface, useAttributionManagerfor live-session attribution, and keep comment-meta as the fallback for users without RTC.The 5 phases
editorIntentpreference (edit/suggest/view), a mode selector in the Options kebab, read-only gating for View intent, keyboard shortcuts, and a "You're suggesting/editing/viewing" snackbar on mode change.editor.BlockEditfilter divertssetAttributesinto a React context so the user sees their edit live but the block-editor store stays at the baseline. The HOC is split so non-Suggest intents only run a singleuseSelect._wp_suggestioncomment meta, theSuggestionsProviderinterface (create/update/delete/apply/reject), and the accept/reject icon buttons in the notes sidebar.This PR (Phase 4)
Review-UX polish + architecture docs + attribute coverage:
SuggestionSummary— compact Docs-style summary rendered in the notes sidebar. DerivesAdd:,Delete:,Formatting:, andFormat:lines from a payload's operations:contentedits produce quotedAdd:/Delete:lines from a word-level diff, ellipsized at 120 characters.<strong>) are detected by comparing visible text with tags stripped and emitFormatting: bold, italicrather than leaking raw<strong>markup.Format:line with human-readable labels.suggestion-mode.spec.jsexercises heading-level changes so non-text attribute suggestions are covered end-to-end alongside the text case.hasAttributeConflict— helper that compares each operation's capturedbeforeto the block's current value. The "apply anyway" confirmation is now scoped per-attribute instead of per-post, so unrelated activity (other blocks, auto-saves, style edits) no longer trips the staleness dialog. Post-levelbaseRevisionis still stamped into the payload for provenance.docs/explanations/architecture/suggestions.mddocuments the provider interface, payload shape, overlay semantics, auto-save timing, conflict detection, and the Yjs v2 migration path.What's NOT in this PR
Phase 4 test plan
Add: "…"/Delete: "…"quotesFormatting: boldand does not leak raw<strong>tagsFormat: heading levelnpm run test:unit -- packages/editor/src/components/suggestion-mode/test/suggestion-summary.jsnpm run test:unit -- packages/editor/src/components/suggestion-mode/test/provider.js --testNamePattern=hasAttributeConflictnpm run test:e2e -- test/e2e/specs/editor/various/suggestion-mode.spec.js🗺️ PR Stack Navigation
_wp_suggestionmeta, provider, sidebar actions📋 Tracking issue: #73411