Phase 3: Explore inline block commenting

[annezazu]

While a discussion broke out years ago around a commenting API, this issue seeks to be a gathering place on what in line commenting could look like today as phase 3 has previously been more firmly announced and early explorations begin. In particular, this area of work is listed as a task for real time collaboration and this issue can act as a gathering place for coordinating what's needed. To pull from this workflows post:

Introduce inline comments on blocks within the editor experience. Explore using comment types to store them. Allow marking comments as resolved. Status of comments also need to fold within individual revisions, so that it’s easy to see what specific edit state a comment refers to. Possible connection with “pending review” functionality.

[poojabhimani12]

Hey Annezazu,

We're excited to share that we've developed this feature and equally thrilled to contribute it to the WordPress core. You can check out the codebase on our GitHub repository here.

Key Features:

• Seamless integration with all Gutenberg core blocks.
• Comment on entire blocks or select specific text within a block.
• Manage comment status: publish, delete, and resolve for each thread.
• An activity panel provides a comprehensive view of all comments and their activities.
• Custom meta handling for comment threads is stored in the Post Meta table.
• Revision support: All comments are stored in post content via custom attributes for accurate restoration.
• You can check compatibility for all blocks here.

Feel free to explore the GitHub repository for a closer look at the functionalities, and don't hesitate to reach out if you have any questions or feedback.

Let's make WordPress collaboration better than ever! 🌐✨

[annezazu]

This is very exciting to see! Big thank you to your crew for being open to contributing your work to Core. It's part of what I hope to see more of with Phase 3.

To move forward, are you all able to split your work into chunks to merge items in a multi-step process? Reviewing the whole repo in one go will be a huge task and smaller items makes it easier to get a sense of the whole. Since you all are experts in your own code and how it's architectured, it would help to have you all lead splitting and integrating it. In terms of general next steps, I had a quick chat with @youknowriad who suggested the following:

1. Introduce the experimental flag for this feature. Here's an example of a recent PR that does this for a different feature: Add Grid interactivity #59052
2. Introduce the low level database structure/whatever custom post types needed. We can then ping some Core PHP folks to review.
3. Introduce the REST endpoint. We can again ensure reviews here.
4. Update the block editor package to support comments.

In some cases, for similar work, folks will create a big POC (proof of concept) PR that's initially opened to serve as an overall guide to the smaller steps. Here's an example: #53455 (comment) You're welcome to do that too to orient the work.

Let me know what questions or guidance is needed so we can collaborate well <3

[poojabhimani12]

Here is the Introduction to database structure.

Comments and related activities are stored within the wp_postmeta, whereas all plugin settings and miscellaneous data reside in the wp_options. Our plugin does not utilize any custom tables.

Comment Meta Data Structure:
When someone comments on a post, we've implemented a sophisticated system for storing comment data using post meta.

• When a user comments on a post, metadata is added with a serialized value.
• Meta Key: _el1710843345082 (prefixed with _el followed by timestamp)
• Meta Value: Serialized array containing comment data, including user data (ID), comment thread content, an assigned user (if any), comment status, commented-on text (block or content), and timestamps.
• If a comment is resolved, additional data is stored, including the resolved status, resolved timestamp, and the user ID of the person who resolved the comment.
• Any edits, deletions, or comments resolved trigger post metadata updates.

Autodraft Comments:

Comments left blank or as autosaves are stored in _autodraft_ids on the post meta.

We add our custom meta key to the WordPress "wp_postmeta" table.

Also I am adding here visual presentation

Introduce the REST endpoint
We've enhanced our REST API endpoints to retrieve data directly from the Post Meta Table.
/cf-get-comments: Retrieves comments via REST API.[check here]
/cf-get-comments-key: Retrieves comment keys via REST API.[check here]
/cf-activities: Retrieves all comments thread [check here]

[jasmussen]

Hello @poojabhimani12, thank you for contributing 🙏

I took a quick review at the various pieces to see how we can best proceed. Keep in mind I'm mainly a design/user experience contributor to the project, and the following should be seen as a first impression.

Experimental flag PR

The PR, as noted, adds an experimental flag for the feature, and adds a button to the block toolbar.

I later reviewed the plugin using the demo that's graciously provided. Quick GIF showing adding inline, block level comments, interacting with existing comments, editing comments, and more:

There are quite a lot of impressive features. Enough that it can also be a bit overwhelming to take in at first, the demo site is no doubt created to show the breadth of features rather than necessarily a typical example of what you might see. But for that reason, I'll rewind a bit, and start with the basics, simply adding a comment.

Adding comments

There are a few ways to do it. Medium has an on-select inline toolbar to surface comment buttons:

Google Docs, perhaps best known for collaboration features, shows an on-select toolbar on the right:

MultiCollab supports both models:

• You can add comments on the block level. Select a block, click the button in the block toolbar. This is denoted by a colored rectangle around the block.
• You can add inline comments. Select any bit of text, press the same block toolbar button.
• There's an additional Google Docs-like toolbar that appears on select, allowing inline comments.

It's also very feature complete:

• Theres' a sidebar inspector panel for resolving/commenting.
• You can also resolve/comment on the bubbles that sit on the right, inside the canvas.
• There's a share button to collaborate.
• There's suggesting, deleting, commenting, marking resolved, adding attachments, editing comments, deleting comments, etc.

It's certainly an impressive featureset, replicating most of what people appreciate about Google Docs.

This also means that there's quite a big surface area for UI that would need to be added and reviewed. As part of that, some details would likely need addressing in order to be compatible with existing UI, meet accessibility criteria, such as using WordPress core components, WordPress icons, leveraging the design system and theme colors, border radii, shadows, borders, etc.

Absorbing the featureset wholesale is likely not going to be feasible, given how much overlap the plugin has with phase 3 features.

The overlap almost certainly comes with a great deal of experience from building everything from multi user editing to share buttons. Because of that, each of those pieces are probably best added separately.

To aid that, the best path forward may be to extract the smallest possible feature-set, polish that to core standards for componentry, design, and accessibility, then ship that. And if it works well, outline a road map of subsquent features and how they might fit in with existing phase 3 collaboration issues.

One outline for how to start could be:

• Start with just comments.
  No comment threads, no suggesting, no accepting changes, perhaps just the ability to dismiss a comment.
• Start with allowing comments only at the block level.
  No inline selection quite yet.
• Start with the "Add comment" action as an item in the block options dropdown, not a button in the block toolbar. It can still have the same shortcut.

We'd most likely want on-select commenting options, and simpler ways to comment. But by starting simple, the structure of the logistics of bringing this to the block editor could be hashed out, what needs rewriting vs. what can be reused would become clearer, and there would be fewer details to get right in order to ship each PR.

Let me know if this makes sense, and thank you again for contributing!