hale-commenting-system 3.5.1 → 3.6.0

package/README.md

@@ -16,8 +16,23 @@ npm uninstall hale-commenting-system
 
 ## Features
 
-- **Pin-based commenting** - Click anywhere on a page to add a comment pin
-- **Thread discussions** - Organize comments into threads with replies
+- **React Component-Based Commenting** - Detects and attaches comments to React components, not just DOM elements
+  - Automatically identifies React component names, types, and props
+  - Shows component tree path (e.g., "App > Dashboard > Button")
+  - Displays component metadata including props in the comment panel
+- **Hover Preview** - See what will be selected before clicking with a visual preview
+  - Dashed blue border highlights the element you're about to select
+  - Component name label appears above the element
+  - Works on all elements including buttons, links, and interactive components
+- **Smart Pin Positioning** - Pins anchor precisely to elements using CSS selectors
+  - Pins appear at the top-left corner of selected components
+  - Automatically follows elements on scroll and resize
+  - Falls back to stored coordinates if element is deleted
+- **Component Highlighting** - Selected components are highlighted with a blue border (similar to Chrome DevTools)
+- **Show Pins Toggle** - View comment pins even when commenting is disabled
+- **Resizable Widget** - Adjust the commenting panel size to fit your workflow
+- **Missing Element Detection** - Pins fade and show [deleted] when target component is removed
+- **Thread Discussions** - Organize comments into threads with replies
 - **GitHub Integration** - Sync comments with GitHub Issues automatically
 - **Jira Integration** - Link Jira tickets to specific pages or sections
 - **PatternFly Design** - Built with PatternFly React components
@@ -140,17 +155,94 @@ After running the integration script, the commenting system will be available in
 
 ### Adding Comments
 
-- **Click anywhere** on a page to add a comment pin
-- **View all comments** in the "Comments" menu item in the sidebar
-- **Reply to comments** to create discussion threads
-- **Navigate to pins** using the "Go to pin" button in the comments view
+1. **Hover to preview** - Move your mouse over any component to see a preview of what will be selected
+   - A dashed blue border highlights the element
+   - A label shows the component or element name
+   - This helps you target the exact component you want to comment on
+
+2. **Click on any component** to attach a comment pin
+   - The system detects React components automatically
+   - Falls back to DOM element detection for non-React elements
+   - Pins anchor to specific elements using CSS selectors
+   - Pins appear at the top-left corner of the selected component
+
+3. **View component information** in the comment panel
+   - **React Components:** Shows component name, type (function/class/memo), component tree path, and props
+   - **DOM Elements:** Shows element description (e.g., "button.pf-c-button")
+   - Components marked as [deleted] if the element is removed from the page
+   - Expandable props section shows all component props in formatted JSON
+
+4. **Pin behavior:**
+   - **Element exists:** Pin positions at top-left corner and follows it on scroll/resize
+   - **Element deleted:** Pin fades to 40% opacity, uses fallback position, and shows [deleted] label
+   - **Selected pin:** Highlighted with blue border around the target component
+
+5. **Control visibility:**
+   - **Enable Comments:** Toggle to enable/disable creating new comments
+   - **Show pins:** Toggle to show/hide pins even when commenting is disabled
+   - Use both toggles to view existing comments without creating new ones
+
+6. **Resize the widget:**
+   - Drag the resize handle in the bottom-right corner of the commenting panel
+   - Adjust width (300-800px) and height (200px to viewport height)
+   - Size is maintained during your session
+
+7. **Navigate and manage comments:**
+   - **View all comments** in the "Comments" menu item in the sidebar
+   - **Reply to comments** to create discussion threads
+   - **Select pins** by clicking on them to view/edit comments
+   - **Close/reopen threads** just like GitHub Issues
+   - **Remove pins** to delete comment threads
+
+### How It Works
+
+The commenting system uses a **hybrid approach** combining React component detection and CSS selectors:
+
+#### React Component Detection (Primary)
+
+1. **Component identification:**
+   - Detects React components using React fiber nodes
+   - Extracts component name, type (function/class/memo/forwardRef), and props
+   - Builds component tree path showing hierarchy (e.g., "App > Dashboard > Button")
+   - Works with all React component types including HOCs and wrapped components
+
+2. **Component metadata:**
+   - Component name (e.g., "Button", "Card", "CustomComponent")
+   - Component type (function, class, memo, forwardRef, etc.)
+   - Component props (sanitized for display, functions shown as [Function])
+   - Component tree path showing parent hierarchy
+
+#### CSS Selector Fallback
+
+For non-React elements or when component detection isn't available:
+
+1. **Priority selection strategy:**
+   - `data-testid` or `data-id` attributes (most stable)
+   - `id` attribute
+   - Combination of tag + class + aria attributes
+   - Fallback to nth-child path
+
+2. **Stored metadata for each pin:**
+   - CSS selector for the target element
+   - React component metadata (if available)
+   - Simplified element/component name for display
+   - Fallback coordinates (if element is deleted)
+
+3. **Example:** Clicking a React Button component might show:
+   - **Component Name:** `Button`
+   - **Component Type:** `function`
+   - **Component Path:** `App > Dashboard > Button`
+   - **Props:** `{ variant: "primary", children: "Submit" }`
+   - **CSS Selector:** `button.pf-c-button[aria-label="Submit"]` (fallback)
 
 ### GitHub Integration (Optional)
 
 When configured, comments automatically sync with GitHub Issues:
-- Each comment thread becomes a GitHub Issue
-- Replies sync as Issue comments
+- Each comment thread becomes a GitHub Issue with component metadata
+- Issue body includes: React component name (if available), CSS selector, and fallback position
+- Replies sync as Issue comments with proper threading
 - Status changes (open/closed) sync between the app and GitHub
+- Component metadata is preserved in issue descriptions
 
 ### Jira Integration (Optional)
 
@@ -196,6 +288,93 @@ The integration script automatically modifies your project:
 5. **`src/app/Comments/Comments.tsx`** - Creates the Comments view component
 6. **`.env` and `.env.server`** - Creates configuration files
 
+## Testing Before Publishing
+
+To test this package locally before publishing to npm:
+
+### Method 1: Using npm link (Recommended)
+
+1. **In the package directory** (hale-npm-package):
+   ```bash
+   npm run build
+   npm link
+   ```
+
+2. **In your test application** (e.g., PatternFly React Seed):
+   ```bash
+   npm link hale-commenting-system
+   npx hale-commenting-system init
+   npm run start:dev
+   ```
+
+3. **Test the features:**
+   - Hover over components to see preview highlighting
+   - Click on various components (buttons, cards, inputs)
+   - Verify pins attach to components and appear at top-left corner
+   - Check that React component metadata is displayed correctly
+   - Scroll/resize and verify pins follow elements
+   - Add comments and replies
+   - Test "Show pins" toggle to view pins without enabling comments
+   - Resize the commenting widget
+   - Remove a component from the DOM and verify pin fades and shows [deleted]
+   - Reload page and verify pins reattach correctly
+
+4. **When done testing:**
+   ```bash
+   # In your test app
+   npx hale-commenting-system remove
+   npm unlink hale-commenting-system
+   npm install
+
+   # In the package directory
+   npm unlink
+   ```
+
+### Method 2: Using npm pack
+
+1. **In the package directory:**
+   ```bash
+   npm run build
+   npm pack
+   ```
+   This creates a `.tgz` file (e.g., `hale-commenting-system-3.6.0.tgz`)
+
+2. **In your test application:**
+   ```bash
+   npm install /path/to/hale-commenting-system-3.5.2.tgz
+   npx hale-commenting-system init
+   npm run start:dev
+   ```
+
+3. **Test and clean up as above**
+
+### Method 3: Using Local Path
+
+1. **In your test application:**
+   ```bash
+   npm install /path/to/hale-npm-package
+   npx hale-commenting-system init
+   npm run start:dev
+   ```
+
+### What to Test
+
+- ✅ **Hover preview** - Verify preview shows correct element and component name
+- ✅ **Pin creation** - Click on different component types (React and DOM elements)
+- ✅ **Pin positioning** - Verify pins appear at top-left corner of elements
+- ✅ **Component detection** - Verify React components show name, type, path, and props
+- ✅ **Component highlighting** - Verify selected components are highlighted with blue border
+- ✅ **Show pins toggle** - Verify pins are visible when toggle is on, even with comments disabled
+- ✅ **Widget resizing** - Verify widget can be resized and maintains size
+- ✅ **Dynamic tracking** - Scroll, resize, and verify pins follow elements
+- ✅ **Element deletion** - Remove components and verify fade + [deleted] label
+- ✅ **Page reload** - Verify pins reattach to correct elements
+- ✅ **Component display** - Check panel shows React component info or DOM element names
+- ✅ **GitHub sync** (if configured) - Verify issues include component metadata
+- ✅ **Comments & replies** - Test threaded discussions
+- ✅ **Close/reopen** - Test thread status changes
+- ✅ **Remove pin** - Verify removing a pin doesn't create a new one
+
 ## Development
 
 ### Running Locally

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hale-commenting-system",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "A commenting system for PatternFly React applications that allows designers and developers to add comments directly on design pages, sync with GitHub Issues, and link Jira tickets.",
   "homepage": "https://www.npmjs.com/package/hale-commenting-system",
   "license": "MIT",
@@ -91,6 +91,8 @@
     "@babel/parser": "^7.23.0",
     "@babel/traverse": "^7.23.0",
     "@babel/types": "^7.23.0",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.1",
     "inquirer": "^8.2.6",
     "node-fetch": "^2.7.0"
   },

package/src/app/commenting-system/components/CommentOverlay.tsx

@@ -3,44 +3,310 @@ import { useLocation } from 'react-router-dom';
 import { useComments } from '../contexts/CommentContext';
 import { CommentPin } from './CommentPin';
 import { getVersionFromPathOrQuery } from '../utils/version';
+import { generateSelectorForElement, getElementDescription, getElementComponentMetadata, findElementBySelector } from '../utils/selectorUtils';
+import { getFiberFromElement, getComponentName } from '../utils/componentUtils';
 
 export const CommentOverlay: React.FunctionComponent = () => {
   const location = useLocation();
-  const { commentsEnabled, addThread, selectedThreadId, setSelectedThreadId, syncFromGitHub, getThreadsForRoute } = useComments();
+  const { commentsEnabled, showPinsEnabled, addThread, selectedThreadId, setSelectedThreadId, syncFromGitHub, getThreadsForRoute } = useComments();
   const detectedVersion = getVersionFromPathOrQuery(location.pathname, location.search);
   const overlayRef = React.useRef<HTMLDivElement>(null);
 
   // Show both open and closed threads as pins (GitHub-style: closed issues still exist)
   const currentThreads = getThreadsForRoute(location.pathname, detectedVersion);
+  const selectedThread = currentThreads.find((t) => t.id === selectedThreadId);
+  const highlightRef = React.useRef<HTMLDivElement | null>(null);
+  const previewRef = React.useRef<HTMLDivElement | null>(null);
+  const previewLabelRef = React.useRef<HTMLDivElement | null>(null);
+  const hoveredElementRef = React.useRef<Element | null>(null);
+
+  // Component highlighting effect (similar to Chrome DevTools)
+  React.useEffect(() => {
+    // Hide highlight when comments are disabled
+    if (!commentsEnabled || !selectedThread || !selectedThread.cssSelector) {
+      // Remove highlight
+      if (highlightRef.current) {
+        highlightRef.current.remove();
+        highlightRef.current = null;
+      }
+      return;
+    }
+
+    const element = findElementBySelector(selectedThread.cssSelector);
+    if (!element) {
+      // Element not found, remove highlight
+      if (highlightRef.current) {
+        highlightRef.current.remove();
+        highlightRef.current = null;
+      }
+      return;
+    }
+
+    // Create or update highlight overlay
+    let highlight = highlightRef.current;
+    if (!highlight) {
+      highlight = document.createElement('div');
+      highlight.style.cssText = `
+        position: fixed;
+        pointer-events: none;
+        z-index: 998;
+        border: 2px solid #0066CC;
+        background-color: rgba(0, 102, 204, 0.1);
+        box-shadow: 0 0 0 1px rgba(0, 102, 204, 0.3);
+        transition: all 0.15s ease;
+      `;
+      document.body.appendChild(highlight);
+      highlightRef.current = highlight;
+    }
+
+    // Update highlight position and size
+    const updateHighlight = () => {
+      if (!highlight || !element) return;
+      const rect = element.getBoundingClientRect();
+      highlight.style.left = `${rect.left + window.scrollX}px`;
+      highlight.style.top = `${rect.top + window.scrollY}px`;
+      highlight.style.width = `${rect.width}px`;
+      highlight.style.height = `${rect.height}px`;
+    };
+
+    updateHighlight();
+
+    // Update on scroll/resize
+    const handleUpdate = () => updateHighlight();
+    window.addEventListener('scroll', handleUpdate, true);
+    window.addEventListener('resize', handleUpdate);
+
+      return () => {
+        window.removeEventListener('scroll', handleUpdate, true);
+        window.removeEventListener('resize', handleUpdate);
+      };
+    }, [commentsEnabled, selectedThreadId, selectedThread]);
+
+  // Cleanup highlight on unmount
+  React.useEffect(() => {
+    return () => {
+      if (highlightRef.current) {
+        highlightRef.current.remove();
+        highlightRef.current = null;
+      }
+      if (previewRef.current) {
+        previewRef.current.remove();
+        previewRef.current = null;
+      }
+      if (previewLabelRef.current) {
+        previewLabelRef.current.remove();
+        previewLabelRef.current = null;
+      }
+    };
+  }, []);
+
+  // Hover preview effect - shows what will be selected before clicking
+  const handleMouseMove = React.useCallback((e: MouseEvent) => {
+    if (!commentsEnabled) {
+      // Remove preview if comments are disabled
+      if (previewRef.current) {
+        previewRef.current.remove();
+        previewRef.current = null;
+      }
+      if (previewLabelRef.current) {
+        previewLabelRef.current.remove();
+        previewLabelRef.current = null;
+      }
+      hoveredElementRef.current = null;
+      return;
+    }
+
+    const target = e.target as HTMLElement;
+    
+    // Don't show preview on comment system UI elements (but allow buttons/links to be selected)
+    if (
+      target.closest('[data-comment-controls]') ||
+      target.closest('[data-comment-pin]') ||
+      target.closest('[data-floating-widget]') ||
+      target.closest('[data-comment-preview]')
+    ) {
+      if (previewRef.current) {
+        previewRef.current.style.display = 'none';
+      }
+      if (previewLabelRef.current) {
+        previewLabelRef.current.style.display = 'none';
+      }
+      hoveredElementRef.current = null;
+      return;
+    }
+
+    // Use the actual element being hovered (don't traverse up for preview)
+    const element = target as Element;
+    
+    // Only update if hovering over a different element
+    if (hoveredElementRef.current === element) {
+      return;
+    }
+    
+    hoveredElementRef.current = element;
+
+    // Get element info for preview - use the actual element, not parent component
+    const elementDescription = getElementDescription(element);
+    
+    // Only get component metadata if this element itself is a React component
+    // Don't traverse up to parent components for preview
+    const fiber = getFiberFromElement(element);
+    let previewName = elementDescription;
+    
+    if (fiber) {
+      const type = fiber.type;
+      // Only use component name if this element IS a React component (not native)
+      if (type && typeof type !== 'string') {
+        const componentName = getComponentName(fiber);
+        const displayName = (typeof type === 'function' && (type.displayName || type.name)) ||
+          (type?.$$typeof === Symbol.for('react.forward_ref') && (type.render?.displayName || type.render?.name)) ||
+          undefined;
+        previewName = componentName || displayName || elementDescription;
+      }
+    }
+
+    // Create or update preview highlight
+    let preview = previewRef.current;
+    if (!preview) {
+      preview = document.createElement('div');
+      preview.setAttribute('data-comment-preview', 'true');
+      preview.style.cssText = `
+        position: fixed;
+        pointer-events: none;
+        z-index: 997;
+        border: 2px dashed #0066CC;
+        background-color: rgba(0, 102, 204, 0.05);
+        box-shadow: 0 0 0 1px rgba(0, 102, 204, 0.2);
+        transition: all 0.1s ease;
+      `;
+      document.body.appendChild(preview);
+      previewRef.current = preview;
+    }
+
+    // Create or update preview label
+    let previewLabel = previewLabelRef.current;
+    if (!previewLabel) {
+      previewLabel = document.createElement('div');
+      previewLabel.setAttribute('data-comment-preview', 'true');
+      previewLabel.style.cssText = `
+        position: fixed;
+        pointer-events: none;
+        z-index: 998;
+        background-color: #0066CC;
+        color: white;
+        padding: 4px 8px;
+        border-radius: 4px;
+        font-size: 12px;
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+        white-space: nowrap;
+        box-shadow: 0 2px 8px rgba(0, 0, 0, 0.2);
+        transition: all 0.1s ease;
+      `;
+      document.body.appendChild(previewLabel);
+      previewLabelRef.current = previewLabel;
+    }
+
+    // Update preview position and size
+    const rect = element.getBoundingClientRect();
+    preview.style.display = 'block';
+    preview.style.left = `${rect.left + window.scrollX}px`;
+    preview.style.top = `${rect.top + window.scrollY}px`;
+    preview.style.width = `${rect.width}px`;
+    preview.style.height = `${rect.height}px`;
+
+    // Update label position (above the element, top-left, but ensure it stays on screen)
+    previewLabel.style.display = 'block';
+    previewLabel.textContent = previewName;
+    
+    const labelLeft = rect.left + window.scrollX;
+    const labelTop = rect.top + window.scrollY - 28;
+    
+    // Ensure label doesn't go off the left edge
+    const adjustedLeft = Math.max(8, labelLeft);
+    
+    // If element is near top of viewport, show label below instead
+    const adjustedTop = labelTop < window.scrollY + 40 
+      ? rect.bottom + window.scrollY + 4 
+      : labelTop;
+    
+    previewLabel.style.left = `${adjustedLeft}px`;
+    previewLabel.style.top = `${adjustedTop}px`;
+  }, [commentsEnabled]);
+
+  // Mouse leave handler to hide preview
+  const handleMouseLeave = React.useCallback(() => {
+    if (previewRef.current) {
+      previewRef.current.style.display = 'none';
+    }
+    if (previewLabelRef.current) {
+      previewLabelRef.current.style.display = 'none';
+    }
+    hoveredElementRef.current = null;
+  }, []);
+
+  // Set up hover preview listeners
+  React.useEffect(() => {
+    if (commentsEnabled) {
+      document.addEventListener('mousemove', handleMouseMove);
+      document.addEventListener('mouseleave', handleMouseLeave, true);
+      
+      return () => {
+        document.removeEventListener('mousemove', handleMouseMove);
+        document.removeEventListener('mouseleave', handleMouseLeave, true);
+      };
+    } else {
+      // Clean up preview when disabled
+      if (previewRef.current) {
+        previewRef.current.remove();
+        previewRef.current = null;
+      }
+      if (previewLabelRef.current) {
+        previewLabelRef.current.remove();
+        previewLabelRef.current = null;
+      }
+      return undefined;
+    }
+  }, [commentsEnabled, handleMouseMove, handleMouseLeave]);
 
   const handlePageClick = (e: MouseEvent) => {
     if (!commentsEnabled) return;
 
-    // Check if clicking on a pin or any interactive element (including FloatingWidget)
+    // Check if clicking on comment system UI elements (but allow buttons/links to be selected)
     const target = e.target as HTMLElement;
     if (
-      target.closest('button') ||
-      target.closest('a') ||
-      target.closest('input') ||
-      target.closest('select') ||
-      target.closest('textarea') ||
-      target.closest('[role="button"]') ||
       target.closest('[data-comment-controls]') ||
       target.closest('[data-comment-pin]') ||
-      target.closest('[data-floating-widget]')
+      target.closest('[data-floating-widget]') ||
+      target.closest('[data-comment-preview]') ||
+      target.closest('button[aria-label*="Remove"]') ||
+      target.closest('button[aria-label*="Delete"]')
     ) {
-      return; // Don't create pin if clicking interactive elements or floating widget
+      return; // Don't create pin if clicking comment system UI or remove/delete buttons
+    }
+    
+    // Also check if the click originated from within the floating widget
+    // This prevents clicks on "Remove pin" button from creating new pins
+    if (e.target && (e.target as Element).closest('[data-floating-widget]')) {
+      return;
     }
 
     // Get the overlay container dimensions (accounts for drawer being open)
     if (!overlayRef.current) return;
     const rect = overlayRef.current.getBoundingClientRect();
 
-    // Calculate percentage based on the content area, not the full window
+    // Calculate percentage based on the content area, not the full window (used as fallback)
     const xPercent = ((e.clientX - rect.left) / rect.width) * 100;
     const yPercent = ((e.clientY - rect.top) / rect.height) * 100;
 
-    const threadId = addThread(xPercent, yPercent, location.pathname, detectedVersion);
+    // Generate CSS selector for the clicked element
+    const clickedElement = target as Element;
+    const cssSelector = generateSelectorForElement(clickedElement);
+    const elementDescription = getElementDescription(clickedElement);
+    
+    // Extract React component metadata (component-based commenting)
+    const componentMetadata = getElementComponentMetadata(clickedElement);
+
+    const threadId = addThread(cssSelector, elementDescription, componentMetadata, xPercent, yPercent, location.pathname, detectedVersion);
     setSelectedThreadId(threadId);
   };
 
@@ -60,14 +326,15 @@ export const CommentOverlay: React.FunctionComponent = () => {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [commentsEnabled, location.pathname, detectedVersion]);
 
-  // Only show pins when commenting is enabled
-  if (!commentsEnabled) {
+  // Show pins when comments are enabled OR when showPinsEnabled is true
+  if (!commentsEnabled && !showPinsEnabled) {
     return null;
   }
 
   return (
     <div
       ref={overlayRef}
+      data-comment-overlay
       style={{
         position: 'absolute',
         top: 0,
@@ -84,6 +351,7 @@ export const CommentOverlay: React.FunctionComponent = () => {
       {currentThreads.map((thread) => (
         <CommentPin
           key={thread.id}
+          cssSelector={thread.cssSelector}
           xPercent={thread.xPercent}
           yPercent={thread.yPercent}
           commentCount={thread.comments.length}