@salesforcedevs/docs-components 1.17.0-hack-alpha5 → 1.17.0-hack-alpha7

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "1.17.0-hack-alpha5",
+    "version": "1.17.0-hack-alpha7",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",

package/src/modules/doc/commentPopup/README.md

@@ -1,71 +1,180 @@
-# Comment Popup Component - Local Storage Implementation
+# Comment Popup Component
 
-This component provides a commenting system that uses browser localStorage for data persistence while the backend API is being developed.
+A Lightning Web Component that allows users to leave comments on documentation sections. The component supports both local storage (for development) and a new API format for production use.
 
 ## Features
 
--   ✅ **Local Storage**: Comments are stored in browser localStorage
--   ✅ **API-Ready**: Code structure prepared for backend integration
--   ✅ **Development Tools**: Helper utilities for managing comments
--   ✅ **Export/Import**: Ability to export comments to JSON files
--   ✅ **Migration Ready**: Tools to convert data for backend migration
+-   ✅ **API Integration**: Now actively tries to fetch from `/get-comments` endpoint
+-   ✅ **Fallback Support**: Falls back to localStorage if API is unavailable
+-   ✅ **New API Format**: Supports branch-based comment fetching
+-   ✅ **Pre-loaded Comments**: Comments are fetched when component is rendered, not when popup opens
+-   ✅ **Local Storage**: Comments persist across page refreshes during development
+-   ✅ **Form Validation**: Email format and required field validation
+-   ✅ **Real-time Display**: Comments appear immediately after posting
+-   ✅ **Timestamp Formatting**: Shows relative time (e.g., "2 hours ago")
+-   ✅ **Email Masking**: Protects user privacy in comment display
+-   ✅ **Comment Count Badge**: Shows total number of comments
+-   ✅ **Responsive Design**: Works on mobile and desktop
+-   ✅ **Keyboard Accessibility**: ESC key to close popup
+-   ✅ **Dark Mode Support**: Adapts to system preferences
+-   ✅ **Development Tools**: Helper utilities for testing
 
-## How It Works
+## API Format
 
-### Storage Structure
+The component now supports a new API format where comments are fetched by branch and then filtered by file path and heading title.
 
-Comments are stored in localStorage under the key `dsc_comments` with the following structure:
+### API Endpoints
+
+-   **GET** `/get-comments?branch={branch}` - Fetch all comments for a branch
+-   **POST** `/post-comment` - Add a new comment
+
+### API Response Format
 
 ```json
 {
-    "branch_filepath_headingtitle": [
+    "request_branch": "feature/documentation-updates",
+    "paths": [
         {
-            "email": "user@example.com",
-            "comment_text": "This is a comment",
-            "timestamp": "2024-01-15T10:30:00Z"
+            "path": "docs/installation.md",
+            "titles": [
+                {
+                    "title": "Installation Guide",
+                    "comments": [
+                        {
+                            "email": "john.doe@example.com",
+                            "comment_text": "This installation guide is very helpful for new users.",
+                            "timestamp": "2024-01-15T10:30:00Z"
+                        }
+                    ]
+                }
+            ]
         }
     ]
 }
 ```
 
-### API Payload Format
-
-When posting comments, the component uses this exact format (ready for backend):
+### API Request Format
 
 ```json
 {
     "branch": "feature/documentation-updates",
     "file_path": "docs/installation.md",
     "heading_title": "Installation Guide",
+    "start_line": "1",
+    "end_line": "50",
     "comment": {
-        "comment_text": "This installation guide is very helpful for new users.",
-        "email": "john.doe@example.com",
+        "comment_text": "This is a helpful comment.",
+        "email": "user@example.com",
         "timestamp": "2024-01-15T10:30:00Z"
     }
 }
 ```
 
+## Usage
+
+### Basic Usage
+
+```html
+<sb-doc-comment-popup
+    heading-title="Installation Guide"
+    file-path="docs/installation.md"
+    current-branch="feature/documentation-updates"
+    start-line="1"
+    end-line="50"
+    open="false"
+    icon-symbol="chat"
+    icon-size="medium"
+>
+</sb-doc-comment-popup>
+```
+
+### Comment Loading Behavior
+
+The component now fetches comments when it is rendered (connected to the DOM) rather than when the popup is opened. This ensures:
+
+-   **Faster Popup Opening**: Comments are already loaded when the user clicks the icon
+-   **Immediate Comment Count**: The comment count badge shows the correct number immediately
+-   **Better User Experience**: No loading delay when opening the popup
+
+Comments are automatically refetched when any of these properties change:
+
+-   `heading-title`
+-   `file-path`
+-   `current-branch`
+
+### Required Properties
+
+-   `heading-title`: The title of the section being commented on
+-   `file-path`: The file path where the comment is located
+-   `current-branch`: The current git branch
+
+### Optional Properties
+
+-   `start-line`: Starting line number (for future line-specific comments)
+-   `end-line`: Ending line number (for future line-specific comments)
+-   `open`: Controls the popup visibility (default: false)
+-   `icon-symbol`: Icon symbol for the comment button (default: "chat")
+-   `icon-size`: Size of the comment icon (default: "medium")
+
+### Available Icon Symbols
+
+-   `chat` - Chat bubble icon
+-   `comment` - Comment icon
+-   `message` - Message icon
+-   `feedback` - Feedback icon
+
+### Available Icon Sizes
+
+-   `small` - Small icon
+-   `medium` - Medium icon (default)
+-   `large` - Large icon
+
+## Local Storage Implementation
+
+During development, the component uses localStorage to persist comments. Comments are stored with a unique key format:
+
+```
+{branch}_{file_path}_{heading_title}
+```
+
+### Local Storage Structure
+
+```json
+{
+    "main_docs/installation.md_Installation Guide": [
+        {
+            "email": "user@example.com",
+            "comment_text": "This is a comment",
+            "timestamp": "2024-01-15T10:30:00Z"
+        }
+    ]
+}
+```
+
 ## Development Tools
 
-### Console Commands
+The component includes development tools for testing and managing comments during development.
 
-When the component is loaded, you can access these functions in the browser console:
+### Console Commands
 
 ```javascript
 // Export all comments to a JSON file
 CommentDevHelper.exportCommentsToFile();
 
-// Clear all comments from localStorage
-CommentDevHelper.clearAllComments();
+// Add sample comments matching the new API format
+CommentDevHelper.addSampleCommentsForNewApi();
 
 // Get statistics about stored comments
 CommentDevHelper.getCommentsStats();
 
-// Convert comments to API format (for backend migration)
-CommentDevHelper.convertToApiFormat();
+// Clear all comments from localStorage
+CommentDevHelper.clearAllComments();
+
+// Test the API response format
+CommentDevHelper.testApiResponseFormat();
 
-// Add a sample comment for testing
-CommentDevHelper.addSampleComment();
+// Simulate API call for a specific branch
+CommentDevHelper.simulateApiCall("main");
 
 // Show all comments in console
 CommentDevHelper.showAllComments();
@@ -73,140 +182,141 @@ CommentDevHelper.showAllComments();
 
 ### Development UI
 
-In development mode (localhost), a floating UI will appear in the top-right corner with buttons to:
+The component automatically creates a development UI when running on localhost. This UI provides buttons for:
 
--   Export comments
--   Clear all comments
--   View statistics
--   Show API format
+-   Adding sample comments
+-   Testing API response format
+-   Exporting comments
+-   Clearing all comments
+-   Viewing statistics
 
-## Migration to Backend
+## API Integration Status
 
-When the backend is ready, follow these steps:
+The component now actively tries to use the backend API with localStorage as a fallback:
 
-### 1. Export Current Comments
+### Current Behavior
 
-```javascript
-// Export all comments to JSON file
-CommentDevHelper.exportCommentsToFile();
-```
+1. **Fetch Comments**: First tries `/get-comments?branch={branch}`, falls back to localStorage if API fails
+2. **Post Comments**: First tries `/post-comment`, falls back to localStorage if API fails
+3. **Error Handling**: Graceful degradation with console warnings for debugging
+4. **Backward Compatibility**: localStorage continues to work for development and offline scenarios
 
-### 2. Convert to API Format
+### API Endpoints
 
-```javascript
-// Get comments in API format
-const apiFormat = CommentDevHelper.convertToApiFormat();
-console.log(apiFormat);
-```
-
-### 3. Uncomment API Code
+-   **GET** `/get-comments?branch={branch}` - Fetch all comments for a branch
+-   **POST** `/post-comment` - Add a new comment
 
-In `commentPopup.ts`, uncomment the API implementation sections:
+### Fallback Strategy
 
 ```typescript
-// Remove the localStorage implementation and uncomment:
-/*
-const response = await fetch('/post-comment', {
-    method: 'POST',
-    headers: {
-        'Content-Type': 'application/json'
-    },
-    body: JSON.stringify(payload)
-});
-*/
+// Fetch comments with fallback
+try {
+    const response = await fetch(`/get-comments?${params.toString()}`);
+    if (response.ok) {
+        // Use API response
+        const data = await response.json();
+        this.comments = this.extractCommentsFromApiResponse(data);
+    } else {
+        // Fallback to localStorage
+        this.comments = await this.getCommentsFromLocalStorage();
+    }
+} catch (error) {
+    // Fallback to localStorage on network error
+    this.comments = await this.getCommentsFromLocalStorage();
+}
 ```
 
-### 4. Update Endpoints
+### Testing API Integration
 
-Update the API endpoints in the component:
+Use the development tools to test API integration:
 
--   POST: `/post-comment` (for adding comments)
--   GET: `/api/comments` (for fetching comments)
+```javascript
+// Test API response format
+CommentDevHelper.testApiResponseFormat();
 
-## File Structure
+// Simulate API call for a specific branch
+CommentDevHelper.simulateApiCall("main");
 
-```
-commentPopup/
-├── commentPopup.ts          # Main component
-├── commentPopup.html        # Template
-├── commentPopup.css         # Styles
-├── commentUtils.ts          # Utility functions
-├── commentDevHelper.ts      # Development tools
-└── README.md               # This file
+// Check if API is available
+CommentDevHelper.checkApiAvailability();
 ```
 
-## Usage
+## Testing
 
-### Basic Usage
+### Storybook Stories
 
-```html
-<c-comment-popup
-    heading-title="Installation Guide"
-    file-path="docs/installation.md"
-    current-branch="main"
->
-</c-comment-popup>
-```
+The component includes comprehensive Storybook stories for testing:
 
-### Required Properties
+1. **Base**: Basic component functionality
+2. **WithNewApiFormatComments**: Testing with new API format
+3. **MultipleBranchesAndFiles**: Testing multiple branches and files
+4. **FormValidation**: Testing form validation features
 
--   `heading-title`: The title of the section being commented on
--   `file-path`: The file path where the comment is located
--   `current-branch`: The current git branch
+### Jest Tests
 
-### Optional Properties
+Run the test suite:
 
--   `start-line`: Starting line number (for future line-specific comments)
--   `end-line`: Ending line number (for future line-specific comments)
--   `open`: Boolean to control popup visibility
+```bash
+npm test commentPopup.test.ts
+```
 
-## Events
+The test suite covers:
 
-The component dispatches these events:
+-   Component initialization
+-   Form validation
+-   Local storage operations
+-   API response format handling
+-   Comment operations
+-   UI interactions
+-   Error handling
+-   Lifecycle methods
 
-```javascript
-// When a comment is added
-element.addEventListener("commentadded", (event) => {
-    console.log("New comment:", event.detail);
-});
-```
+## Troubleshooting
 
-## Browser Compatibility
+### Common Issues
 
--   Modern browsers with localStorage support
--   IE10+ (with polyfills if needed)
+1. **Comments not appearing**: Check that `heading-title`, `file-path`, and `current-branch` are set correctly
+2. **Form validation errors**: Ensure email format is valid and all required fields are filled
+3. **localStorage errors**: Check browser console for localStorage quota exceeded errors
+4. **API integration issues**: Verify API endpoints and response format match expected structure
 
-## Storage Limits
+### Debug Commands
 
--   localStorage typically has a 5-10MB limit
--   Comments are stored as JSON strings
--   Monitor storage usage with `CommentDevHelper.getCommentsStats()`
+```javascript
+// Check current comments
+console.log(CommentDevHelper.getAllComments());
 
-## Troubleshooting
+// Check component state
+console.log(element.comments);
+console.log(element.email);
+console.log(element.comment);
+
+// Test API response parsing
+CommentDevHelper.testApiResponseFormat();
+```
 
-### Comments Not Appearing
+## Browser Support
 
-1. Check browser console for errors
-2. Verify localStorage is enabled
-3. Check if the comment key matches: `branch_filepath_headingtitle`
+-   Chrome 60+
+-   Firefox 55+
+-   Safari 12+
+-   Edge 79+
 
-### Storage Issues
+## Dependencies
 
-1. Clear localStorage: `CommentDevHelper.clearAllComments()`
-2. Export existing comments before clearing
-3. Check browser storage limits
+-   Lightning Web Components (LWC)
+-   TypeScript
+-   Jest (for testing)
 
-### Development UI Not Showing
+## Contributing
 
-1. Ensure you're on localhost
-2. Check if the UI was manually closed
-3. Refresh the page to recreate the UI
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Update documentation
+6. Submit a pull request
 
-## Future Enhancements
+## License
 
--   [ ] Line-specific comments
--   [ ] Comment threading/replies
--   [ ] Comment moderation
--   [ ] User authentication integration
--   [ ] Real-time comment updates
--   [ ] Comment search and filtering
+This component is part of the Salesforce Developer Documentation Components package.