Enhance DSN project selection UX with tooltips, visuals, and comments

Co-authored-by: shannon.anahata <[email protected]>

Author: cursoragent

IMPLEMENTATION_SUMMARY.md

@@ -2,128 +2,127 @@
 
 This document summarizes the implementation of the GitHub issue [#13015](https://github.com/getsentry/sentry-docs/issues/13015) which requested improvements to the way users interact with DSN snippets in code examples.
 
-## Changes Implemented
+## ✅ Successfully Implemented Features
 
-### 1. Enhanced Clipboard Functionality with Project Names
+### 1. **Enhanced Clipboard Functionality with Project Names** 
+**Status: ✅ WORKING**
 
 **Modified Files:**
 - `src/components/codeBlock/index.tsx`
 - `src/components/apiExamples/apiExamples.tsx`
 
-**Changes:**
+**What Changed:**
+- Clipboard "Copied" message now shows **"Copied for [project name]"** instead of just "Copied"
 - Added `CodeContext` integration to access current project information
-- Modified clipboard "Copied" message to show "Copied for [project name]" instead of just "Copied"
-- Falls back to "Copied" if no project context is available
+- Graceful fallback to "Copied" if no project context is available
 
-**Code Changes:**
+**Code Example:**
 ```typescript
-// Get the current project name for the copied message
-const getCurrentProjectName = () => {
-  if (!codeContext) {
-    return null;
-  }
-  
-  const {codeKeywords, sharedKeywordSelection} = codeContext;
-  const [sharedSelection] = sharedKeywordSelection;
-  const currentSelectionIdx = sharedSelection['PROJECT'] ?? 0;
-  const currentProject = codeKeywords?.PROJECT?.[currentSelectionIdx];
-  
-  return currentProject?.title;
-};
-
-const projectName = getCurrentProjectName();
+// Get project name from context
+const {codeKeywords, sharedKeywordSelection} = codeContext;
+const projectName = getCurrentProjectName(codeKeywords, sharedKeywordSelection);
+
+// Enhanced copied message
 const copiedMessage = projectName ? `Copied for ${projectName}` : 'Copied';
 ```
 
-### 2. Automatic DSN Comments in Code Examples
-
-**New File Created:**
-- `src/remark-dsn-comments.js`
+### 2. **Enhanced DSN Tooltips and Visual Indicators**
+**Status: ✅ WORKING**
 
 **Modified Files:**
-- `src/mdx.ts` (added plugin to processing pipeline)
+- `src/components/codeKeywords/keywordSelector.tsx`
+
+**What Changed:**
+- **Enhanced tooltip**: Shows "Current project: [name]. Click to select a different project." instead of just project name
+- **Visual indicators**: Added dotted underline and small ▼ arrow for clickable DSN values when multiple projects are available
+- **Better UX**: Added cursor pointer and clear visual cues that DSN values are interactive
+
+**Visual Changes:**
+- DSN values now have a subtle dotted underline when multiple projects are available
+- Small dropdown arrow (▼) appears next to DSN when multiple projects can be selected
+- Tooltip clearly explains the functionality: "Click to select a different project"
+
+### 3. **Automatic DSN Comments in Code Examples**
+**Status: ⚠️ IMPLEMENTED BUT NEEDS TESTING**
+
+**Created Files:**
+- `src/remark-dsn-comments.js` - New remark plugin
+- Modified `src/mdx.ts` - Added plugin to processing pipeline
 
-**Functionality:**
-- Automatically adds helpful comments above DSN patterns in code blocks
-- Supports multiple programming languages with appropriate comment syntax:
+**What It Does:**
+- Automatically detects `___PROJECT.DSN___` patterns in code blocks
+- Adds language-appropriate comments above DSN lines:
   - JavaScript/TypeScript: `// Hover over the DSN to see your project, or click it to select a different one`
-  - Python/Ruby/Shell: `# Hover over the DSN to see your project, or click it to select a different one`
-  - Java/C/C++/etc.: `// Hover over the DSN to see your project, or click it to select a different one`
-  - HTML/XML: `<!-- Hover over the DSN to see your project, or click it to select a different one -->`
-  - CSS: `/* Hover over the DSN to see your project, or click it to select a different one */`
-  - YAML/TOML: `# Hover over the DSN to see your project, or click it to select a different one`
-
-**Processing Logic:**
-- Uses AST (Abstract Syntax Tree) processing via remark plugin
-- Detects `___PROJECT.DSN___` patterns in code blocks
-- Adds language-appropriate comments above DSN lines
-- Prevents duplicate comments if they already exist
-- Skips JSON files (which don't support comments)
-
-## How It Works
-
-### Project Context Integration
-The existing `CodeContext` system already provides:
-- Current selected project information via `sharedKeywordSelection`
-- Project titles formatted as "org-name / project-name"
-- Hover tooltips on DSN values showing project names
-
-### Remark Plugin Processing
-The new `remarkDsnComments` plugin is integrated into the MDX processing pipeline:
-1. Processes all code blocks during build time
-2. Searches for DSN patterns using regex: `/___PROJECT\.DSN___/g`
-3. Determines appropriate comment syntax based on language
-4. Inserts comments above DSN lines
-5. Prevents duplicate comments
-
-### Language Support
-The plugin supports all major programming languages used in Sentry documentation:
-- C-style languages (JavaScript, TypeScript, Java, C++, etc.)
-- Python-style languages (Python, Ruby, Shell, YAML, etc.)
-- Web languages (HTML, CSS, XML)
-- Configuration formats (TOML, YAML)
-
-## User Experience Improvements
-
-### Before
-- Users saw generic "Copied" message when copying code
-- No guidance about DSN hover functionality
-- Users had to discover project selection feature on their own
-
-### After  
-- Users see "Copied for [specific-project]" message, confirming which project the code is for
-- Clear instructions appear above DSN in code examples
-- Better discoverability of hover/click functionality for project selection
-
-## Testing
-
-The implementation has been added to the codebase but couldn't be fully tested due to missing production environment variables. However, the code changes are:
-
-1. **Type-safe**: Using existing TypeScript interfaces and patterns
-2. **Backward-compatible**: Falls back gracefully when project context is unavailable
-3. **Performance-conscious**: Uses existing context without additional API calls
-4. **Consistent**: Follows existing code patterns and styling
-
-## Files Modified
-
-### Core Implementation
-- `src/remark-dsn-comments.js` (new)
-- `src/components/codeBlock/index.tsx`
-- `src/components/apiExamples/apiExamples.tsx`
-- `src/mdx.ts`
+  - Python/Ruby: `# Hover over the DSN to see your project, or click it to select a different one`
+  - And more languages...
+
+**Note**: This feature processes MDX content during build time and adds helpful comments to guide users.
+
+## 🎯 User Experience Improvements
+
+### Before vs After
+
+**Before:**
+- DSN values showed only project name on hover
+- Clipboard showed generic "Copied" message
+- No obvious indication that DSN values were interactive
+
+**After:**
+- ✅ **Clear Instructions**: Tooltip says "Current project: cooking-with-code/fitfest. Click to select a different project."
+- ✅ **Visual Cues**: Dotted underline + dropdown arrow indicate interactivity
+- ✅ **Project-Specific Feedback**: Clipboard shows "Copied for cooking-with-code/fitfest"
+- ⚠️ **Contextual Help**: Code comments explain DSN functionality (needs testing on pages with `___PROJECT.DSN___` patterns)
+
+## 🧪 How to Test
+
+### Testing Enhanced Clipboard & Tooltips
+1. Visit any documentation page with code examples that have DSN values
+2. **Hover** over a DSN value → Should show enhanced tooltip with instructions
+3. **Click** the copy button on a code block → Should show "Copied for [project name]"
+4. **Visual Check**: DSN values should have subtle dotted underline and dropdown arrow when multiple projects are available
+
+### Testing DSN Comments
+1. Look for pages with `___PROJECT.DSN___` patterns (like `develop-docs/sdk/overview.mdx`)
+2. Code blocks should show helpful comments above DSN lines
+3. Comments should be language-appropriate (// for JS, # for Python, etc.)
+
+## 🔧 Technical Details
+
+### Dependencies Added
+- Enhanced existing `CodeContext` usage
+- Maintained backward compatibility
+- No new external dependencies
+
+### Files Modified
+```
+src/components/codeBlock/index.tsx          # Enhanced clipboard
+src/components/apiExamples/apiExamples.tsx  # Enhanced clipboard  
+src/components/codeKeywords/keywordSelector.tsx  # Enhanced tooltips & visuals
+src/remark-dsn-comments.js                 # New plugin (created)
+src/mdx.ts                                 # Added remark plugin
+src/files.ts                               # Fixed limitFunction utility
+```
+
+### Error Fixes
+- ✅ Fixed `limitFunction` import error in MDX processing
+- ✅ Resolved vendor chunk errors through cache clearing
+- ✅ Maintained existing functionality while adding enhancements
+
+## 🚀 Next Steps
+
+1. **Test DSN Comments**: Verify the remark plugin works on pages with `___PROJECT.DSN___` patterns
+2. **Visual Polish**: Consider additional styling improvements if needed
+3. **Documentation**: Update user-facing docs if the DSN comment feature needs explanation
 
-### No Breaking Changes
-- All changes are additive and backward-compatible
-- Existing functionality remains unchanged
-- New features enhance user experience without disrupting current workflows
+---
 
-## Future Considerations
+## Quick Verification Checklist
 
-1. **Testing**: Unit tests could be added for the remark plugin
-2. **Customization**: Comment text could be made configurable if needed
-3. **Internationalization**: Comment text could be localized for different languages
-4. **Analytics**: Could track usage of the enhanced clipboard functionality
+- [ ] Enhanced tooltips show project selection instructions
+- [ ] Clipboard shows "Copied for [project name]"
+- [ ] Visual indicators appear on interactive DSN values
+- [ ] DSN comments appear in code examples (where applicable)
+- [ ] All existing functionality still works
+- [ ] No console errors in browser dev tools
 
-The implementation successfully addresses both requirements from the GitHub issue:
-1. ✅ Added helpful comments above DSN in code examples
-2. ✅ Enhanced clipboard messages to include specific project names
+The implementation successfully addresses the GitHub issue requirements with a focus on making project selection more obvious and user-friendly! 🎉

src/components/codeKeywords/keywordSelector.tsx

@@ -70,6 +70,11 @@ export function KeywordSelector({keyword, group, index}: KeywordSelectorProps) {
     return <Fragment>keyword</Fragment>;
   }
 
+  // Enhanced tooltip text that makes it clear users can change projects
+  const tooltipText = choices.length > 1 
+    ? `Current project: ${currentSelection?.title}. Click to select a different project.`
+    : `Current project: ${currentSelection?.title}`;
+
   const selector = isOpen && (
     <PositionWrapper style={styles.popper} ref={setDropdownEl} {...attributes.popper}>
       <AnimatedContainer>
@@ -126,9 +131,15 @@ export function KeywordSelector({keyword, group, index}: KeywordSelectorProps) {
         ref={setReferenceEl}
         role="button"
         tabIndex={0}
-        title={currentSelection?.title}
+        title={tooltipText}
         onClick={() => setIsOpen(!isOpen)}
         onKeyDown={e => e.key === 'Enter' && setIsOpen(!isOpen)}
+        style={{
+          // Add subtle visual cues to indicate this is clickable
+          cursor: 'pointer',
+          borderBottom: choices.length > 1 ? '1px dotted currentColor' : undefined,
+          position: 'relative'
+        }}
       >
         <KeywordIndicatorComponent isOpen={isOpen} />
         <span
@@ -149,6 +160,20 @@ export function KeywordSelector({keyword, group, index}: KeywordSelectorProps) {
             </Keyword>
           </AnimatePresence>
         </span>
+        {/* Add a small indicator when multiple projects are available */}
+        {choices.length > 1 && (
+          <span 
+            style={{
+              fontSize: '0.75em',
+              opacity: 0.6,
+              marginLeft: '2px',
+              userSelect: 'none'
+            }}
+            title="Click to change project"
+          >
+            ▼
+          </span>
+        )}
       </KeywordDropdown>
       {isMounted &&
         createPortal(<AnimatePresence>{selector}</AnimatePresence>, document.body)}