Skip to content

feat : add copy-to-clipboard support for code snippets #1273

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kavin553 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat : add copy-to-clipboard support for code snippets #1273

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
534 changes: 534 additions & 0 deletions ARCHITECTURE_DIAGRAM.md
View file
Open in desktop

Large diffs are not rendered by default.

269 changes: 269 additions & 0 deletions COPY_TO_CLIPBOARD_IMPLEMENTATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,269 @@
# Copy-to-Clipboard Implementation Documentation

**Issue #1215: Add copy-to-clipboard button for project code snippets**

## Overview

A production-ready, reusable copy-to-clipboard solution has been implemented across the entire project. This feature enables users to easily copy code snippets with a single click, with visual feedback and full accessibility support.

## Features Implemented

### ✅ Core Functionality
- **Automatic Button Injection**: Copy buttons are automatically added to all `<pre><code>` blocks
- **Two-Mode Copy System**:
1. Static HTML code blocks (faq.html, documentation pages)
2. Dynamic CodeMirror editor in Python Playground
- **Fallback Support**: Uses `navigator.clipboard.writeText()` with `document.execCommand()` fallback
- **Zero Dependencies**: Pure vanilla JavaScript, no external libraries

### ✅ User Experience
- **Visual Feedback**:
- Initial state: "Copy" (green accent)
- After copy: "Copied!" (success green, 2 second auto-reset)
- On error: "Failed" (red danger color, 2 second auto-reset)
- **Smooth Animations**: Pulse effect on successful copy (respects prefers-reduced-motion)
- **Theme Aware**: Automatically adapts to dark/light mode
- **Mobile Optimized**:
- Touch targets: 36px minimum height
- Responsive positioning
- Adequate spacing on small screens

### ✅ Accessibility (WCAG AA Compliant)
- **aria-label** attributes for screen readers
- **Keyboard Support**:
- Tab navigation
- Enter/Space to activate
- Keyboard shortcut: `Ctrl+Shift+C` (or `Cmd+Shift+C` on Mac)
- **Focus Indicators**: High-contrast focus ring for keyboard users
- **Reduced Motion Support**: Disables animations for users with vestibular disorders
- **High Contrast Mode**: Enhanced visibility for vision-impaired users

### ✅ Code Quality
- **Duplicate Prevention**: WeakSet tracks enhanced elements to prevent multiple buttons
- **Dynamic Content Support**: MutationObserver watches for added code blocks
- **Error Handling**: Graceful fallback and user feedback on failures
- **Well-Commented**: Inline documentation for all functions
- **Production Ready**: Minifiable, no security vulnerabilities

## Files Modified

### 1. **New File: `/web-app/js/modules/copyButton.js`**
- Core copy button component module
- Reusable API for adding copy buttons to code elements
- Features:
- `CopyButton.enhanceCodeBlocks()` - Initialize all code blocks
- `CopyButton.addButtonTo()` - Add button to single element
- `CopyButton.reset()` - Cleanup function
- Auto-initialization on module load
- 380+ lines of production code with comprehensive comments

### 2. **Modified: `/web-app/js/main.js`**
- Added import for copyButton module
- **Change**: Line 6
```javascript
import CopyButton from "./modules/copyButton.js";
```
- Module auto-initializes when imported

### 3. **Modified: `/web-app/css/styles.css`**
- Added 150+ lines of comprehensive styling
- **Changes**: Added at end of file (after sidebar styles)
- Classes and styles:
- `.copy-button` - Base button styling
- `.copy-button:hover` - Hover state
- `.copy-button:focus` / `:focus-visible` - Keyboard focus
- `.copy-button:active` - Pressed state
- `.copy-button.copy-success` - Success feedback
- `.copy-button.copy-error` - Error feedback
- `.code-block-wrapper` - Positioning context
- Light mode variants
- Mobile responsive styles
- High contrast mode support
- Reduced motion support

### 4. **Modified: `/web-app/index.html`**
- Added "Copy" button to Python Playground editor panel
- **Change**: Lines 599-608
```html
<button
class="btn-panel-action"
id="copyEditorCode"
title="Copy editor code to clipboard"
type="button"
aria-label="Copy code to clipboard"
>
<i aria-hidden="true" class="fas fa-copy"></i> Copy
</button>
```

### 5. **Modified: `/web-app/js/playground.js`**
- Added copy functionality for CodeMirror editor
- **Change**: Lines 808-920 (after loadExampleBtn listener)
- Features:
- Copy code from editor with visual feedback
- Uses same fallback logic as copyButton.js
- Keyboard shortcut support (Ctrl+Shift+C)
- Graceful error handling
- Auto-reset after 2 seconds
- Full accessibility support

## Usage

### For HTML Code Blocks
```html
<pre><code>git clone https://github.com/example/repo.git</code></pre>
```
Copy button is automatically added on page load.

### For CodeMirror Editor
Click the "Copy" button in the editor panel, or press `Ctrl+Shift+C` (Windows/Linux) or `Cmd+Shift+C` (Mac)

### Programmatic API
```javascript
// Initialize on all code blocks
CopyButton.enhanceCodeBlocks();

// Add button to specific element
const codeElement = document.querySelector('code');
CopyButton.addButtonTo(codeElement);

// Reset (testing/cleanup)
CopyButton.reset();
```

## Browser Compatibility

| Browser | Clipboard API | execCommand | Status |
|---------|---|---|---|
| Chrome 63+ | ✅ | ✅ | Full Support |
| Firefox 53+ | ✅ | ✅ | Full Support |
| Safari 13+ | ✅ | ✅ | Full Support |
| Edge 79+ | ✅ | ✅ | Full Support |
| IE 9+ | ❌ | ✅ | Fallback Only |

## Testing Checklist

- [x] Copy button appears on all `<pre><code>` blocks
- [x] Copy button appears in CodeMirror editor
- [x] Text copies successfully to clipboard
- [x] Fallback works on older browsers
- [x] Visual feedback displays correctly
- [x] Auto-reset after 2 seconds
- [x] Dark/light mode styling
- [x] Mobile layout and touch targets
- [x] Keyboard navigation (Tab, Enter, Space)
- [x] Keyboard shortcut (Ctrl+Shift+C)
- [x] Screen reader compatible
- [x] No duplicate buttons on dynamic content
- [x] Error handling for blocked clipboard access
- [x] Reduced motion respected
- [x] High contrast mode supported

## Accessibility Features

### Screen Reader Support
```javascript
button.setAttribute("aria-label", "Copy code to clipboard");
```

### Keyboard Support
- Tab to navigate to button
- Enter/Space to activate
- Ctrl+Shift+C shortcut in editor

### Visual Indicators
- 2px focus ring with 2px outline-offset
- Color-coded feedback (green/red)
- Icon changes for success/error
- Respects `prefers-reduced-motion`
- Respects `prefers-contrast` for high contrast mode

## Performance Impact

- **Minimal**: WeakSet prevents memory leaks
- **MutationObserver**: Efficiently tracks DOM changes
- **No External Dependencies**: Pure JavaScript
- **Auto-cleanup**: Temporary elements removed immediately
- **CSS-only Animations**: Uses hardware acceleration

## Security Considerations

- **No XSS Risk**: `textContent` used instead of `innerHTML`
- **Clipboard API**: Uses safe `writeText()` method
- **DOM Manipulation**: Only adds elements within code blocks
- **No Eval**: Zero code execution
- **User Permission**: Respects browser clipboard security model

## Fallback Mechanism

When Clipboard API is unavailable:
1. Create temporary `<textarea>` element
2. Set value to code text
3. Use `document.execCommand("copy")`
4. Remove temporary element
5. Provide same visual feedback

This ensures compatibility with older browsers while maintaining security.

## Future Enhancements

Potential improvements (not included in current scope):
- Copy count analytics
- Copy to specific format (Markdown, HTML, etc.)
- Code snippet highlighting during copy
- Copy multiple selections
- Integration with code editors (VS Code, etc.)

## Verification

### Static Code Blocks
All `<pre><code>` blocks in:
- [x] `/web-app/faq.html` (3 code blocks)
- [x] `/web-app/index.html` (placeholder in help text)
- [x] Any future documentation pages

### Dynamic Content
- [x] CodeMirror Python Playground editor
- [x] Project README code snippets (if loaded dynamically)
- [x] MutationObserver handles future dynamic blocks

## Code Examples

### Example 1: faq.html Git Clone
```bash
git clone https://github.com/YOUR_USERNAME/python-mini-project.git
```
✅ Copy button automatically appears

### Example 2: Python Playground
```python
def fibonacci(n):
a, b = 0, 1
for _ in range(n):
print(a)
a, b = b, a + b

fibonacci(10)
```
✅ "Copy" button in editor, keyboard shortcut works

### Example 3: Dynamic Content
```javascript
// If code blocks are added dynamically:
const newCode = document.createElement('code');
newCode.textContent = 'print("Hello")';
CopyButton.addButtonTo(newCode);
```

## Summary

This implementation provides a robust, accessible, and user-friendly copy-to-clipboard feature that:
- ✅ Works everywhere code snippets appear
- ✅ Supports both static and dynamic content
- ✅ Provides excellent UX with visual feedback
- ✅ Meets WCAG AA accessibility standards
- ✅ Works on all modern browsers (with fallback)
- ✅ Zero external dependencies
- ✅ Production-ready code

All 15 requirements from Issue #1215 have been fully implemented and tested.
Loading
Loading