@salesforcedevs/docs-components 1.17.0-hack-alpha4 → 1.17.0-hack-alpha6

package/package.json

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

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

@@ -0,0 +1,294 @@
+# Comment Popup Component
+
+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
+
+-   ✅ **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
+
+## API Format
+
+The component now supports a new API format where comments are fetched by branch and then filtered by file path and heading title.
+
+### API Endpoints
+
+-   **GET** `/get-comments?branch={branch}` - Fetch all comments for a branch
+-   **POST** `/post-comment` - Add a new comment
+
+### API Response Format
+
+```json
+{
+    "request_branch": "feature/documentation-updates",
+    "paths": [
+        {
+            "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 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 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
+
+The component includes development tools for testing and managing comments during development.
+
+### Console Commands
+
+```javascript
+// Export all comments to a JSON file
+CommentDevHelper.exportCommentsToFile();
+
+// Add sample comments matching the new API format
+CommentDevHelper.addSampleCommentsForNewApi();
+
+// Get statistics about stored comments
+CommentDevHelper.getCommentsStats();
+
+// Clear all comments from localStorage
+CommentDevHelper.clearAllComments();
+
+// Test the API response format
+CommentDevHelper.testApiResponseFormat();
+
+// Simulate API call for a specific branch
+CommentDevHelper.simulateApiCall("main");
+
+// Show all comments in console
+CommentDevHelper.showAllComments();
+```
+
+### Development UI
+
+The component automatically creates a development UI when running on localhost. This UI provides buttons for:
+
+-   Adding sample comments
+-   Testing API response format
+-   Exporting comments
+-   Clearing all comments
+-   Viewing statistics
+
+## Migration to Backend API
+
+When the backend API is ready, follow these steps to migrate from localStorage:
+
+1. **Uncomment API calls**: In `commentPopup.ts`, uncomment the API implementation sections
+2. **Comment localStorage calls**: Comment out the localStorage implementation sections
+3. **Update API endpoints**: Ensure the API endpoints match your backend
+4. **Test API integration**: Use the development tools to test API calls
+
+### Example Migration
+
+```typescript
+// Before (localStorage)
+await this.saveCommentToLocalStorage(payload);
+
+// After (API)
+const response = await fetch("/post-comment", {
+    method: "POST",
+    headers: {
+        "Content-Type": "application/json"
+    },
+    body: JSON.stringify(payload)
+});
+```
+
+## Testing
+
+### Storybook Stories
+
+The component includes comprehensive Storybook stories for testing:
+
+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
+
+### Jest Tests
+
+Run the test suite:
+
+```bash
+npm test commentPopup.test.ts
+```
+
+The test suite covers:
+
+-   Component initialization
+-   Form validation
+-   Local storage operations
+-   API response format handling
+-   Comment operations
+-   UI interactions
+-   Error handling
+-   Lifecycle methods
+
+## Troubleshooting
+
+### Common Issues
+
+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
+
+### Debug Commands
+
+```javascript
+// Check current comments
+console.log(CommentDevHelper.getAllComments());
+
+// Check component state
+console.log(element.comments);
+console.log(element.email);
+console.log(element.comment);
+
+// Test API response parsing
+CommentDevHelper.testApiResponseFormat();
+```
+
+## Browser Support
+
+-   Chrome 60+
+-   Firefox 55+
+-   Safari 12+
+-   Edge 79+
+
+## Dependencies
+
+-   Lightning Web Components (LWC)
+-   TypeScript
+-   Jest (for testing)
+
+## Contributing
+
+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
+
+## License
+
+This component is part of the Salesforce Developer Documentation Components package.

package/src/modules/doc/commentPopup/commentDevHelper.ts

@@ -0,0 +1,321 @@
+// Development Helper for Comment Management
+// This file provides a simple interface to manage comments during development
+// You can use this in the browser console or create a simple UI for it
+
+import {
+    exportCommentsToFile,
+    importCommentsFromFile,
+    getAllComments,
+    clearAllComments,
+    getCommentsStats,
+    convertToApiFormat,
+    addComment,
+    getCommentsForBranch,
+    fetchCommentsForBranch,
+    extractCommentsFromApiResponse
+} from "./commentUtils";
+
+// Make functions available globally for console access
+if (typeof window !== "undefined") {
+    (window as any).CommentDevHelper = {
+        exportCommentsToFile,
+        importCommentsFromFile,
+        getAllComments,
+        clearAllComments,
+        getCommentsStats,
+        convertToApiFormat,
+        addComment,
+        getCommentsForBranch,
+        fetchCommentsForBranch,
+        extractCommentsFromApiResponse
+    };
+}
+
+/**
+ * Create a simple UI for managing comments during development
+ */
+export function createDevUI(): void {
+    if (typeof document === "undefined") {
+        return;
+    }
+
+    // Check if UI already exists
+    if (document.getElementById("comment-dev-ui")) {
+        return;
+    }
+
+    const ui = document.createElement("div");
+    ui.id = "comment-dev-ui";
+    ui.style.cssText = `
+        position: fixed;
+        top: 20px;
+        right: 20px;
+        width: 350px;
+        background: white;
+        border: 2px solid #007bff;
+        border-radius: 8px;
+        padding: 16px;
+        font-family: Arial, sans-serif;
+        font-size: 14px;
+        z-index: 10000;
+        box-shadow: 0 4px 12px rgba(0,0,0,0.15);
+        max-height: 80vh;
+        overflow-y: auto;
+    `;
+
+    const stats = getCommentsStats();
+
+    ui.innerHTML = `
+        <div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 12px;">
+            <h3 style="margin: 0; color: #007bff;">Comment Dev Helper</h3>
+            <button onclick="document.getElementById('comment-dev-ui').remove()" style="background: none; border: none; font-size: 18px; cursor: pointer;">×</button>
+        </div>
+        
+        <div style="margin-bottom: 12px;">
+            <strong>Stats:</strong><br>
+            Branches: ${stats.branches.length}<br>
+            Locations: ${stats.totalLocations}<br>
+            Total Comments: ${stats.totalComments}
+        </div>
+        
+        <div style="display: flex; flex-direction: column; gap: 8px;">
+            <button onclick="CommentDevHelper.exportCommentsToFile()" style="padding: 8px; background: #28a745; color: white; border: none; border-radius: 4px; cursor: pointer;">
+                Export Comments
+            </button>
+            
+            <button onclick="CommentDevHelper.clearAllComments()" style="padding: 8px; background: #dc3545; color: white; border: none; border-radius: 4px; cursor: pointer;">
+                Clear All Comments
+            </button>
+            
+            <button onclick="CommentDevHelper.getCommentsStats()" style="padding: 8px; background: #17a2b8; color: white; border: none; border-radius: 4px; cursor: pointer;">
+                Show Stats in Console
+            </button>
+            
+            <button onclick="console.log(CommentDevHelper.convertToApiFormat())" style="padding: 8px; background: #6f42c1; color: white; border: none; border-radius: 4px; cursor: pointer;">
+                Show API Format in Console
+            </button>
+            
+            <button onclick="CommentDevHelper.addSampleCommentsForNewApi()" style="padding: 8px; background: #fd7e14; color: white; border: none; border-radius: 4px; cursor: pointer;">
+                Add Sample Comments (New API Format)
+            </button>
+            
+            <button onclick="CommentDevHelper.testApiResponseFormat()" style="padding: 8px; background: #20c997; color: white; border: none; border-radius: 4px; cursor: pointer;">
+                Test API Response Format
+            </button>
+        </div>
+        
+        <div style="margin-top: 12px; font-size: 12px; color: #666;">
+            <strong>Console Commands:</strong><br>
+            CommentDevHelper.exportCommentsToFile()<br>
+            CommentDevHelper.clearAllComments()<br>
+            CommentDevHelper.getCommentsStats()<br>
+            CommentDevHelper.convertToApiFormat()<br>
+            CommentDevHelper.getCommentsForBranch('main')<br>
+            CommentDevHelper.testApiResponseFormat()
+        </div>
+    `;
+
+    document.body.appendChild(ui);
+}
+
+/**
+ * Remove the development UI
+ */
+export function removeDevUI(): void {
+    const ui = document.getElementById("comment-dev-ui");
+    if (ui) {
+        ui.remove();
+    }
+}
+
+/**
+ * Add sample comments that match the new API format
+ */
+export function addSampleCommentsForNewApi(): void {
+    const sampleComments = [
+        {
+            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",
+                timestamp: new Date(Date.now() - 3600000).toISOString() // 1 hour ago
+            }
+        },
+        {
+            branch: "feature/documentation-updates",
+            file_path: "docs/installation.md",
+            heading_title: "Installation Guide",
+            start_line: "1",
+            end_line: "50",
+            comment: {
+                comment_text:
+                    "Consider adding troubleshooting section for common issues.",
+                email: "jane.smith@example.com",
+                timestamp: new Date(Date.now() - 1800000).toISOString() // 30 minutes ago
+            }
+        },
+        {
+            branch: "feature/documentation-updates",
+            file_path: "docs/installation.md",
+            heading_title: "Prerequisites",
+            start_line: "10",
+            end_line: "25",
+            comment: {
+                comment_text:
+                    "The prerequisites section is clear and well-organized.",
+                email: "mike.wilson@example.com",
+                timestamp: new Date(Date.now() - 900000).toISOString() // 15 minutes ago
+            }
+        },
+        {
+            branch: "feature/documentation-updates",
+            file_path: "docs/api.md",
+            heading_title: "API Reference",
+            start_line: "1",
+            end_line: "100",
+            comment: {
+                comment_text:
+                    "The API documentation needs more examples for authentication.",
+                email: "sarah.jones@example.com",
+                timestamp: new Date(Date.now() - 600000).toISOString() // 10 minutes ago
+            }
+        },
+        {
+            branch: "feature/documentation-updates",
+            file_path: "docs/api.md",
+            heading_title: "API Reference",
+            start_line: "1",
+            end_line: "100",
+            comment: {
+                comment_text: "Great work on the endpoint descriptions!",
+                email: "david.brown@example.com",
+                timestamp: new Date().toISOString() // now
+            }
+        },
+        {
+            branch: "main",
+            file_path: "docs/getting-started.md",
+            heading_title: "Quick Start",
+            start_line: "1",
+            end_line: "30",
+            comment: {
+                comment_text:
+                    "This quick start guide is perfect for beginners.",
+                email: "alice.johnson@example.com",
+                timestamp: new Date(Date.now() - 7200000).toISOString() // 2 hours ago
+            }
+        }
+    ];
+
+    sampleComments.forEach((comment) => {
+        addComment(comment);
+    });
+
+    console.log("Added sample comments for new API format");
+    console.log("Sample data includes multiple branches, files, and titles");
+
+    // Refresh the page to show the new comments
+    setTimeout(() => {
+        window.location.reload();
+    }, 1000);
+}
+
+/**
+ * Test the API response format
+ */
+export function testApiResponseFormat(): void {
+    console.log("=== Testing API Response Format ===");
+
+    // Test with feature/documentation-updates branch
+    const featureBranchResponse = getCommentsForBranch(
+        "feature/documentation-updates"
+    );
+    console.log("Feature branch response:", featureBranchResponse);
+
+    // Test with main branch
+    const mainBranchResponse = getCommentsForBranch("main");
+    console.log("Main branch response:", mainBranchResponse);
+
+    // Test extracting specific comments
+    const installationComments = extractCommentsFromApiResponse(
+        featureBranchResponse,
+        "docs/installation.md",
+        "Installation Guide"
+    );
+    console.log("Installation Guide comments:", installationComments);
+
+    const apiComments = extractCommentsFromApiResponse(
+        featureBranchResponse,
+        "docs/api.md",
+        "API Reference"
+    );
+    console.log("API Reference comments:", apiComments);
+
+    console.log("=== API Response Format Test Complete ===");
+}
+
+/**
+ * Show all comments in a formatted way in the console
+ */
+export function showAllComments(): void {
+    const allComments = getAllComments();
+    console.log("=== ALL COMMENTS ===");
+    console.table(allComments);
+
+    const stats = getCommentsStats();
+    console.log("=== STATISTICS ===");
+    console.table(stats.locations);
+
+    console.log("=== BRANCHES ===");
+    console.log("Available branches:", stats.branches);
+}
+
+/**
+ * Simulate API call and show response
+ */
+export async function simulateApiCall(
+    branch: string = "feature/documentation-updates"
+): Promise<void> {
+    console.log(`=== Simulating API Call for branch: ${branch} ===`);
+
+    try {
+        const response = await fetchCommentsForBranch(branch);
+        console.log("API Response:", response);
+
+        // Show all paths and titles
+        response.paths.forEach((path) => {
+            console.log(`File: ${path.path}`);
+            path.titles.forEach((title) => {
+                console.log(
+                    `  Title: ${title.title} (${title.comments.length} comments)`
+                );
+            });
+        });
+    } catch (error) {
+        console.error("API call simulation failed:", error);
+    }
+}
+
+// Add the helper functions to the global CommentDevHelper
+if (typeof window !== "undefined") {
+    (window as any).CommentDevHelper = {
+        ...(window as any).CommentDevHelper,
+        addSampleCommentsForNewApi,
+        testApiResponseFormat,
+        showAllComments,
+        simulateApiCall
+    };
+}
+
+// Auto-create UI when this module is imported (in development)
+if (typeof window !== "undefined" && window.location.hostname === "localhost") {
+    // Only auto-create in development environment
+    setTimeout(() => {
+        createDevUI();
+    }, 1000);
+}