Comments on block elements

[max-nextcloud]

Summary

Initial sketch with available comments indicated in text and a button to create a new comment on the current active section.

Allow comments on block elements (paragraphs, headings, quotes, ...):

• Allow create comments.
• Display existing comments.
• Allow removing ones own comments.

Motivation

Comments are useful in many situation. They allow adding information that directly relates to parts of the document without adding it directly to the document content.

Comments can be particularly helpful when drafting documents and during a review process.

Comments on block elements attach the comment to the relevant section on the document while avoiding the complexity of in line comments such as overlapping comment ranges.

Specification

Comments can be added to all block elements:

• Paragraphs
• Headings
• Quotes
• Callouts
• Code blocks
• Images
• Link Previews
• Tables
• all types of Lists

Alternatives

Inline comments

This draft mainly came out of the discussion of in line comments in #185. In line comments allow commenting on a precise range of text, which is hard to represent in markdown.

Footnotes

While footnotes could also be used to represent comments, they serve a different purpose.

2142 discusses footnotes.

User Interface Elements

• Button to add a comment to a block element
• Indicator that there are comments on an element
• List of comments on an element
• Button to remove ones own comment

Implementation

• Comments will be serialized in markdown.
• They will be implemented using the standard way in text:
  • Markdown-it extension parses them to html.
  • Tiptap nodes represent them in the editor.
  • toMarkdown function to serialize them.
• Comments can contain multiple block nodes themselves.

Out of scope for now (but maybe future)

• Edit my own comments.
• Reply to other comments.
• Suggest changes.
• Integrate with nextcloud comments system.
• Integrate with document chat (talk).
• Notify about comments.

[nimishavijay]

References

Google docs


Notion


Confluence


Design specs

Existing comments

• [ ] Highlight the text (not the block, that looks too, well... blocky 😀) in color-primary-element-light at 0.5 opacity
  • [ ] Nice-to-have: a border-bottom: 2px solid var(--color-primary-element) also with 0.5 opacity
• [ ] On hover: highlight opacity: 1
• [ ] On click: highlight opacity: 1 and the comment opens

• [ ] Comment box: max-width: 300px
• [ ] Show avatar (34px), name, and comment with actions in a 3dot menu
  • [ ] nice-to-have: timestamp
• [ ] Actions in the 3 dot menu: Delete if it's user's comment
  • [ ] nice-to-have: "Mark as resolved" if it is not user's comment

New comments

• [ ] When the cursor is in a block or when you hover on a block, a comment button should appear (TBD: where and how it looks)
• [ ] When you click on comment button:
  • [ ] text in block gets highlight (opacity 1)
  • [ ] New comment element opens

New comment element:

• [ ] Show user's avatar (24px), name, input field, comment and cancel buttons
• [ ] When you click on comment, the comment gets added and is shown as normal

Mobile view

Mockups TBD

• [ ] Don't show the comment icon next to the block, instead show it on the top bar
• [ ] Existing comments are stickied to right below the block they are associated to
• [ ] Same for new comments, plus the keyboard opens

TBD:

• [ ] Placement and exact of the comment button next to the block (left side? right side? secondary button? shadow?)
• [ ] Placement of comment action in the top bar
• [ ] Should there be a "Show/hide comments" toggle in the top bar?
• [ ] Interaction of comments and author colors
• [ ] How to show comments from different people:
  • do we need it for the MVP?
  • different colored highlight?
  • comment indication with avatar?

What do you think? :)