Env docs with feedback applied

Author: yoen-velt

async-collaboration/comments/customize-behavior.mdx

@@ -90,7 +90,7 @@ commentElement.addCommentOnSelectedText();
 
 Adds a Comment on a specific element by ID.
 
-To add a comment on a specific element through an API method, use the `addCommentOnElement()` method and pass in an object with the schema shown in the examples:
+To add a comment on a specific element through an API method, use the `addCommentOnElement()` method and pass in an object with the schema shows in the example:
 
 **Example 1: Add comment with targetElementId only:**
 
@@ -100,17 +100,17 @@ To add a comment on a specific element through an API method, use the `addCommen
 ```jsx
 const element = {
   "targetElement": {
-    "elementId": "element_id",
+    "elementId": "element_id",  // optional (pass elementId if you want to add comment on a specific element)
     "targetText": "target_text", // optional (pass targetText if you want to add comment on a specific text)
     "occurrence": 1, // optional (default: 1) This is relevant for text comment. By default, we will attach comment to the first occurence of the target text in your document. You can change this to attach your comment on a more specific text.
   	"selectAllContent": true, // Set to `true` if you want to select all the text content of the target element.
   },
   "commentData": [
     {
-      "commentText": "This is awesome! Well done.",
-      "commentHtml": "This <span style=\"color: green; background-color: aliceblue; display: inline-block; padding: 4px; border-radius: 4px;\">is test</span> comment.",
-      "replaceContentText": "This is new comment",
-      "replaceContentHtml": "<span>This is <b>new</b> comment.</span>",
+      "commentText": "This is awesome! Well done.", // To set plain text content
+      "commentHtml": "This <span style=\"color: green; background-color: aliceblue; display: inline-block; padding: 4px; border-radius: 4px;\">is test</span> comment.", // To set HTML formatted content
+      "replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with
+      "replaceContentHtml": "<span>This is <b>new</b> comment.</span>", // If replacement text contains html formatted text, then provide it here
     }
   ],
   "status": "open", // optional (default: open)
@@ -126,17 +126,17 @@ commentElement.addCommentOnElement(element);
 ```jsx
 const element = {
   "targetElement": {
-    "elementId": "element_id",
+    "elementId": "element_id", // optional (pass elementId if you want to add comment on a specific element)
     "targetText": "target_text", // optional (pass targetText if you want to add comment on a specific text)
     "occurrence": 1, // optional (default: 1) This is relevant for text comment. By default, we will attach comment to the first occurence of the target text in your document. You can change this to attach your comment on a more specific text.
   	"selectAllContent": true, // Set to `true` if you want to select all the text content of the target element.
   },
   "commentData": [
     {
-      "commentText": "This is awesome! Well done.",
-      "commentHtml": "This <span style=\"color: green; background-color: aliceblue; display: inline-block; padding: 4px; border-radius: 4px;\">is test</span> comment.",
-      "replaceContentText": "This is new comment",
-      "replaceContentHtml": "<span>This is <b>new</b> comment.</span>",
+      "commentText": "This is awesome! Well done.", // To set plain text content
+      "commentHtml": "This <span style=\"color: green; background-color: aliceblue; display: inline-block; padding: 4px; border-radius: 4px;\">is test</span> comment.", // To set HTML formatted content
+      "replaceContentText": "This is new comment", // provide this replaceContentText to replace current text with
+      "replaceContentHtml": "<span>This is <b>new</b> comment.</span>", // If replacement text contains html formatted text, then provide it here
     }
   ],
   "status": "open", // optional (default: open)
@@ -148,58 +148,6 @@ commentElement.addCommentOnElement(element);
 </Tab>
 </Tabs>
 
-**Example 2: Add comment with context metadata:**
-
-<Tabs>
-<Tab title="React / Next.js">
-
-```jsx
-const element = {
-  "targetElement": {
-    "elementId": "element_id",
-  },
-  "commentData": [
-    {
-      "commentText": "This is awesome! Well done.",
-    }
-  ],
-  "context": {
-    "product": "cheese",
-    "location": "zurich"
-  },
-  "status": "open",
-}
-
-const commentElement = client.getCommentElement();
-commentElement.addCommentOnElement(element);
-```
-</Tab>
-
-<Tab title="Other Frameworks">
-
-```jsx
-const element = {
-  "targetElement": {
-    "elementId": "element_id",
-  },
-  "commentData": [
-    {
-      "commentText": "This is awesome! Well done.",
-    }
-  ],
-  "context": {
-    "product": "cheese",
-    "location": "zurich"
-  },
-  "status": "open",
-}
-
-const commentElement = Velt.getCommentElement();
-commentElement.addCommentOnElement(element);
-```
-</Tab>
-</Tabs>
-
 #### addManualComment
 - This feature is particularly useful for complex UIs where you need precise control over the placement of Comment Pins.
 - Using this you can manually set the position of Comment Annotations.
@@ -2118,33 +2066,18 @@ Extra fields in the comment context don't prevent a match.
 { product: "cheese", category: "dairy"} ❌ No match (missing field)
 ```
 
-**Example 1: Comment Bubble with Partial Match**
+**Example**
 
 <Tabs>
 <Tab title="React / Next.js">
 ```jsx
+{/* Comment Bubble with Partial Match */}
 <VeltCommentBubble
   context={{ product: "cheese" }}
   contextOptions={{ partialMatch: true }}
 />
-```
-</Tab>
-<Tab title="Other Frameworks">
-```html
-<velt-comment-bubble
-  context='{ "product": "cheese" }'
-  context-options='{ "partialMatch": true }'
->
-</velt-comment-bubble>
-```
-</Tab>
-</Tabs>
 
-**Example 2: Comment Tool with Partial Match**
-
-<Tabs>
-<Tab title="React / Next.js">
-```jsx
+{/* Comment Tool with Partial Match */}
 <VeltCommentTool
   targetElementId="element_id"
   context={{ product: "cheese" }}
@@ -2154,6 +2087,14 @@ Extra fields in the comment context don't prevent a match.
 </Tab>
 <Tab title="Other Frameworks">
 ```html
+<!-- Comment Bubble with Partial Match -->
+<velt-comment-bubble
+  context='{ "product": "cheese" }'
+  context-options='{ "partialMatch": true }'
+>
+</velt-comment-bubble>
+
+<!-- Comment Tool with Partial Match -->
 <velt-comment-tool
   target-element-id="element_id"
   context='{ "product": "cheese" }'

async-collaboration/comments/setup/popover.mdx

@@ -44,7 +44,7 @@ This component is required to render comments in your app. Popover mode means co
 ```
 
 </Tab>
-<Tab title="HTML">
+<Tab title="Other Frameworks">
 
 Add the comment component to your template close to the root level of your `<body>`.
 
@@ -70,6 +70,7 @@ Add a Comment Tool near each cell or element you want to comment on. For example
 - Add unique DOM ID to each element
 - Set the `targetElementId` to match the element's ID
 - When users click on the Comment Tool, it attaches a Comment to that element
+- If your app is more complex and cannot have unique IDs for each element (e.g., table cell), you could also use `context` to bind the element and comment with custom metadata, which can then be used to filter, group, and render comments that match specific criteria. [Learn more](/async-collaboration/comments/customize-behavior#aggregation)
 
 ![](/images/comment-tool.png)
 
@@ -116,7 +117,8 @@ Add a Comment Tool in a single location such as the navigation bar.
 
 - Add unique DOM ID and `data-velt-target-comment-element-id` attribute to each element (both with the same value)
 - When users click on the Comment Tool and then click on the target element, it attaches a Comment to it
-- You can only add one Comment per element with this approach
+- You can only add one Comment Annotation (thread) per element with this approach
+- If your app is more complex and cannot have unique IDs for each element (e.g., table cell), you could also use `context` to bind the element and comment with custom metadata, which can then be used to filter, group, and render comments that match specific criteria. [Learn more](/async-collaboration/comments/customize-behavior#aggregation)
 
 <Warning>
 If you don't add the `data-velt-target-comment-element-id` attribute, you will be adding multiple Comment Annotations on the same element.
@@ -157,11 +159,10 @@ If you don't add the `data-velt-target-comment-element-id` attribute, you will b
 
 ## Step 4: Add Metadata to the Comment
 
-You can add metadata to comments to:
-- Render additional data on comments
-- Position comment pins manually
+- Render additional data on comments UI
 - Create custom UI components
 - Enable comment filtering on custom data
+- Use the metadata later when processing notifications
 
 ### a. Using Comment Tool
 
@@ -196,7 +197,7 @@ Either use this or the default triangle component. Using both could cause visual
 
 The Comment Bubble component:
 - Displays a count of replies for a comment thread
-- Must have the same `targetElementId` as its associated element
+- Must have the same `targetElementId` or `context` as its associated element and comment tool
 - Can show either total replies or only unread replies
 - Can be placed anywhere in your UI
 
@@ -252,7 +253,7 @@ The Comment Bubble component:
 </Tab>
 </Tabs>
 
-## Step 6: Remove Popover Mode Triangle (optional)
+### Remove Popover Mode Triangle (optional)
 
 ![](/images/popover-comment-pin.png)
 
@@ -293,7 +294,7 @@ commentElement.disablePopoverTriangleComponent();
 </Tab>
 </Tabs>
 
-## Step 7: Test Integration
+## Step 6: Test Integration
 
 Test it out by opening the page with Velt components in your browser.
 
@@ -319,23 +320,26 @@ export default function App() {
     <VeltProvider apiKey="API_KEY">
       <VeltComments popoverMode={true} popoverTriangleComponent={true} />
 
-      {/* Comment Tool next to each element */}
+      {/* Pattern a: Comment Tool next to each element */}
       <div className="table">
-        <div className="cell" id="cell-id-1">
-          <VeltCommentTool targetElementId="cell-id-1" />
+        <div className="cell" id="cell-1">
+          <VeltCommentTool targetElementId="cell-1" />
+          <VeltCommentBubble targetElementId="cell-1" />
         </div>
-        <div className="cell" id="cell-id-2">
-          <VeltCommentBubble targetElementId="cell-id-2" />
+        <div className="cell" id="cell-2">
+          <VeltCommentTool targetElementId="cell-2" />
         </div>
       </div>
 
-      {/* Single Comment Tool */}
+      {/* Pattern b: Single Comment Tool */}
       <div>
-        <VeltCommentTool/>
+        <VeltCommentTool />
         <div className="table">
-          <div className="cell" data-velt-target-comment-element-id="cell-id-A" id="cell-id-A">
+          <div className="cell" id="cell-A" data-velt-target-comment-element-id="cell-A">
+            Content
           </div>
-          <div className="cell" data-velt-target-comment-element-id="cell-id-B" id="cell-id-B">
+          <div className="cell" id="cell-B" data-velt-target-comment-element-id="cell-B">
+            Content
           </div>
         </div>
       </div>
@@ -348,36 +352,33 @@ export default function App() {
 <Tab title="HTML">
 
 ```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <title>Comment documentation</title>
-  </head>
-  <body>
-    <velt-comments popover-triangle-component="true"></velt-comments>
-
-    <!-- Comment Tool next to each element -->
-    <div class="table">
-      <div class="cell" id="cell-id-1">
-        <velt-comment-tool target-element-id="cell-id-1"></velt-comment-tool>
-      </div>
-      <div class="cell" id="cell-id-2">
-        <velt-comment-bubble target-element-id="cell-id-2"></velt-comment-bubble>
-      </div>
+<body>
+  <velt-comments popover-mode="true" popover-triangle-component="true"></velt-comments>
+
+  <!-- Pattern a: Comment Tool next to each element -->
+  <div class="table">
+    <div class="cell" id="cell-1">
+      <velt-comment-tool target-element-id="cell-1"></velt-comment-tool>
+      <velt-comment-bubble target-element-id="cell-1"></velt-comment-bubble>
+    </div>
+    <div class="cell" id="cell-2">
+      <velt-comment-tool target-element-id="cell-2"></velt-comment-tool>
     </div>
+  </div>
 
-    <!-- Single Comment Tool -->
-    <div>
-      <velt-comment-tool></velt-comment-tool>
-      <div class="table">
-        <div class="cell" data-velt-target-comment-element-id="cell-id-A" id="cell-id-A">
-        </div>
-        <div class="cell" data-velt-target-comment-element-id="cell-id-B" id="cell-id-B">
-        </div>
+  <!-- Pattern b: Single Comment Tool -->
+  <div>
+    <velt-comment-tool></velt-comment-tool>
+    <div class="table">
+      <div class="cell" id="cell-A" data-velt-target-comment-element-id="cell-A">
+        Content
+      </div>
+      <div class="cell" id="cell-B" data-velt-target-comment-element-id="cell-B">
+        Content
       </div>
     </div>
-  </body>
-</html>
+  </div>
+</body>
 ```
 
 </Tab>

async-collaboration/comments/setup/tiptap.mdx

@@ -32,7 +32,7 @@ title: "Tiptap Setup"
 #### Step 2: Install the Velt Tiptap extension
 
 ```bash
-npm i @veltdev/tiptap-velt-comments @tiptap/react @tiptap/starter-kit
+npm i @veltdev/tiptap-velt-comments
 ```
 
 #### Step 3: Import and add the extension to your Tiptap editor
@@ -94,6 +94,7 @@ Add a button in your existing bubble menu or create a new bubble menu that appea
             <BubbleMenu editor={editor} tippyOptions={{ duration: 100 }}>
               <div className="bubble-menu">
                 <button
+                  className="comment-button"
                   onClick={(e) => {
                     e.preventDefault();
                     e.stopPropagation();
@@ -117,11 +118,27 @@ Add a button in your existing bubble menu or create a new bubble menu that appea
     ```
   </Tab>
   <Tab title="Other Frameworks">
+    ```html
+    <!-- HTML Structure -->
+    <div id="editor"></div>
+    <div class="bubble-menu">
+      <button class="comment-button" title="Add comment">
+        <svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg" stroke="currentColor">
+          <path
+            d="M10 17.25H4C3.30964 17.25 2.75 16.6904 2.75 16V10C2.75 5.99594 5.99594 2.75 10 2.75C14.0041 2.75 17.25 5.99594 17.25 10C17.25 14.0041 14.0041 17.25 10 17.25Z"
+            stroke-width="1.5"
+          />
+        </svg>
+      </button>
+    </div>
+    ```
+
     ```js
     import { BubbleMenu, Editor } from '@tiptap/core';
     import { addComment } from '@veltdev/tiptap-velt-comments';
 
     const editor = new Editor({
+      element: document.querySelector('#editor'),
       // ... your editor configuration
     });
 
@@ -155,7 +172,7 @@ Refer to the [Tiptap BubbleMenu documentation](https://tiptap.dev/docs/editor/ex
 #### Step 5: Call `addComment` to add a comment
 
 - Call this method to add a comment to selected text in the Tiptap editor. You can use this when the user clicks on the comment button in context menu or presses a keyboard shortcut.
-- Params: `AddCommentRequest`. It has the following properties:
+- Params: [`AddCommentRequest`](/api-reference/sdk/models/data-models#addcommentrequest). It has the following properties:
   - `editor`: instance of the Tiptap editor.
   - `editorId`: Id of the tiptap editor. Use this if you have multiple tiptap editors on the same page in your app. (optional)
   - `context`: Add any custom metadata to the Comment Annotation. [Learn more](/async-collaboration/comments/customize-behavior#metadata). (optional)
@@ -198,7 +215,7 @@ Refer to the [Tiptap BubbleMenu documentation](https://tiptap.dev/docs/editor/ex
 #### Step 6: Render Comments in Tiptap Editor
 
 - Get the comment data from Velt SDK and render it in the Tiptap Editor.
-- Params: `RenderCommentsRequest`. It has the following properties:
+- Params: [`RenderCommentsRequest`](/api-reference/sdk/models/data-models#rendercommentsrequest). It has the following properties:
   - `editor`: Instance of the Tiptap editor.
   - `editorId`: Id of the tiptap editor. Use this if you have multiple tiptap editors on the same page in your app. (optional)
   - `commentAnnotations`: Array of Comment Annotation objects.