@salesforcedevs/docs-components 1.17.0-hack-alpha8 → 1.17.2-accessfix-alpha

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

@@ -1,322 +0,0 @@
-# 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
-
--   ✅ **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
-
-## 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
-
-## API Integration Status
-
-The component now actively tries to use the backend API with localStorage as a fallback:
-
-### Current Behavior
-
-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
-
-### API Endpoints
-
--   **GET** `/get-comments?branch={branch}` - Fetch all comments for a branch
--   **POST** `/post-comment` - Add a new comment
-
-### Fallback Strategy
-
-```typescript
-// 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();
-}
-```
-
-### Testing API Integration
-
-Use the development tools to test API integration:
-
-```javascript
-// Test API response format
-CommentDevHelper.testApiResponseFormat();
-
-// Simulate API call for a specific branch
-CommentDevHelper.simulateApiCall("main");
-
-// Check if API is available
-CommentDevHelper.checkApiAvailability();
-```
-
-## 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

@@ -1,380 +0,0 @@
-// 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,
-        checkApiAvailability
-    };
-}
-
-/**
- * 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);
-    }
-}
-
-/**
- * Check if the API endpoints are available
- */
-export async function checkApiAvailability(): Promise<void> {
-    console.log("=== Checking API Availability ===");
-
-    try {
-        // Test GET endpoint
-        const getResponse = await fetch("/get-comments?branch=test");
-        console.log(
-            `GET /get-comments status: ${getResponse.status} ${getResponse.statusText}`
-        );
-
-        if (getResponse.ok) {
-            console.log("✅ GET /get-comments is available");
-        } else {
-            console.log("❌ GET /get-comments is not available");
-        }
-
-        // Test POST endpoint (with a test payload)
-        const testPayload = {
-            branch: "test",
-            file_path: "test.md",
-            heading_title: "Test",
-            start_line: "1",
-            end_line: "10",
-            comment: {
-                comment_text: "Test comment",
-                email: "test@example.com",
-                timestamp: new Date().toISOString()
-            }
-        };
-
-        const postResponse = await fetch("/post-comment", {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/json"
-            },
-            body: JSON.stringify(testPayload)
-        });
-
-        console.log(
-            `POST /post-comment status: ${postResponse.status} ${postResponse.statusText}`
-        );
-
-        if (postResponse.ok) {
-            console.log("✅ POST /post-comment is available");
-        } else {
-            console.log("❌ POST /post-comment is not available");
-        }
-
-        console.log("=== API Availability Check Complete ===");
-    } catch (error) {
-        console.error("❌ API availability check failed:", error);
-        console.log("This is expected if the backend is not running");
-    }
-}
-
-// 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);
-}