docs: add comprehensive zoom implementation technical documentation

- Document CSS zoom vs transform scale decision - Explain inverse zoom technique for fixed elements - Detail viewport expansion strategy - Cover edge cases, constraints, and browser compatibility - Include testing checklist and future considerations
2025-11-12 17:04:45 +00:00
parent 3a381ee111
commit 927d257f2c
1 changed files with 332 additions and 0 deletions
@@ -0,0 +1,332 @@
 # Zoom Implementation - Technical Documentation
 ## Overview
 This document describes the technical implementation of the custom zoom feature in the CV application, including architectural decisions, constraints, and solutions to specific challenges.
 ## Implementation Summary
 - **Range**: 25% - 175% (centered at 100%)
 - **Technology**: CSS `zoom` property on wrapper element
 - **Fixed Elements**: Action bar, zoom control, info button, back-to-top button
 - **Viewport Behavior**: Horizontal scroll enabled when zoomed > 100%
 ## Technical Architecture
 ### 1. Core Zoom Application
 **Location**: `static/js/main.js` - `applyZoom()` function
 ```javascript
 function applyZoom(zoomValue, saveToStorage = true) {
    const zoomWrapper = document.getElementById('zoom-wrapper');
    const zoomLevel = zoomValue / 100;
    // Apply CSS zoom to wrapper
    zoomWrapper.style.zoom = zoomLevel;
    // Allow horizontal expansion when zoomed > 100%
    if (zoomLevel > 1) {
        zoomWrapper.style.minWidth = `${window.innerWidth}px`;
    } else {
        zoomWrapper.style.minWidth = '';
    }
    // Apply inverse zoom to fixed buttons
    const inverseZoom = 1 / zoomLevel;
    document.getElementById('back-to-top').style.zoom = inverseZoom;
    document.getElementById('info-button').style.zoom = inverseZoom;
 }
 ```
 ### 2. HTML Structure
 **Location**: `templates/index.html`
 ```html
 <!-- Fixed elements (NOT affected by zoom) -->
 <div class="action-bar">...</div>
 <nav class="navigation-menu">...</nav>
 <!-- Zoomable content wrapper -->
 <div id="zoom-wrapper" class="zoom-wrapper">
    <div class="cv-container">
        <main class="cv-paper">
            <!-- CV content here -->
        </main>
    </div>
 </div>
 <!-- Fixed elements (NOT affected by zoom) -->
 <footer>...</footer>
 <button id="back-to-top">...</button>
 <button id="info-button">...</button>
 <div id="zoom-control">...</div>
 ```
 ## Critical Design Decisions
 ### Decision 1: CSS `zoom` vs `transform: scale()`
 **Choice**: CSS `zoom` property
 **Why**:
 - **Layout impact**: `zoom` affects actual layout dimensions, making scrollbars appear naturally
 - **Footer positioning**: With `zoom`, footer automatically follows zoomed content
 - **Browser behavior**: Mimics native browser zoom behavior more closely
 **Why NOT `transform: scale()`**:
 - Only visual transformation, doesn't affect layout
 - Creates infinite gray space below content
 - Requires complex margin calculations to position footer
 - Doesn't trigger natural scrollbar behavior
 ### Decision 2: Inverse Zoom for Fixed Elements
 **Problem**: CSS `zoom` on parent can affect fixed-position children in some rendering contexts
 **Solution**: Apply inverse zoom to elements that must stay constant size
 ```javascript
 const inverseZoom = 1 / zoomLevel;
 button.style.zoom = inverseZoom;
 ```
 **Example**:
 - Content zoom: 150% (1.5)
 - Button inverse zoom: 66.67% (1/1.5)
 - Result: Button appears at 100% (1.5 × 0.667 = 1.0)
 **Affected Elements**:
 - `#back-to-top` button
 - `#info-button` button
 - Note: `#zoom-control` and `.action-bar` are naturally outside zoom context
 ### Decision 3: Viewport Expansion Strategy
 **Problem**: Elements with `width: 100%` stay constrained to viewport even when zoomed
 **Solution**: Set `min-width` on zoom wrapper when zoom > 100%
 ```javascript
 if (zoomLevel > 1) {
    zoomWrapper.style.minWidth = `${window.innerWidth}px`;
 }
 ```
 **Effect**:
 - Content can expand beyond viewport width
 - Horizontal scrollbar appears automatically
 - User can scroll to see all zoomed content
 **CSS Support**:
 ```css
 body {
    overflow-x: auto; /* Enable horizontal scroll */
 }
 ```
 ## Constraints and Limitations
 ### 1. Browser Compatibility
 **CSS `zoom` property**:
 - ✅ Chrome, Edge, Safari: Full support
 - ⚠️ Firefox: Supported since Firefox 126 (May 2024)
 - Fallback: Content remains at 100% zoom in unsupported browsers
 ### 2. Range Limitations
 **Current Range**: 25% - 175%
 **Why centered at 100%**:
 - Slider midpoint = (25 + 175) / 2 = 100
 - Users expect "reset" to be at slider center
 - Provides balanced zoom-in/zoom-out range
 **Why NOT 50% - 200%**:
 - 50% minimum would make slider center = 125%, confusing UX
 - Current range provides adequate zoom range while maintaining intuitive controls
 ### 3. Fixed Element Positioning
 **Elements that MUST stay outside zoom-wrapper**:
 - Action bar (navigation)
 - Zoom control
 - Fixed buttons (info, back-to-top)
 - Footer
 **If placed inside zoom-wrapper**:
 - Would scale with content
 - Requires inverse zoom application (added complexity)
 - Footer positioning becomes unreliable
 ### 4. Performance Considerations
 **CSS `zoom` Performance**:
 - Generally performant (GPU-accelerated in modern browsers)
 - Can cause reflow when changed
 - Mitigated by `requestAnimationFrame()` wrapper
 **Optimization**:
 ```javascript
 requestAnimationFrame(() => {
    zoomWrapper.style.zoom = zoomLevel;
    // Other DOM modifications
 });
 ```
 ### 5. Mobile Behavior
 **Current Implementation**: Zoom control hidden on mobile (≤768px viewport)
 **Rationale**:
 - Mobile browsers provide native pinch-to-zoom
 - Custom zoom control redundant on touch devices
 - Saves screen space on small viewports
 **Code**:
 ```javascript
 function isMobileView() {
    return window.innerWidth <= 768;
 }
 ```
 ## Edge Cases Handled
 ### 1. Zoom Persistence
 **Behavior**: Zoom level saved to `localStorage`
 ```javascript
 localStorage.setItem('cv-zoom', zoomValue.toString());
 ```
 **On Page Load**: Restore saved zoom level
 ```javascript
 const savedZoom = localStorage.getItem('cv-zoom');
 if (savedZoom) {
    applyZoom(parseInt(savedZoom, 10), false);
 }
 ```
 ### 2. Responsive Resize
 **Problem**: User resizes window while zoomed
 **Solution**: Recalculate min-width on window resize
 ```javascript
 window.addEventListener('resize', function() {
    // Debounced resize handler
    if (isMobileView()) {
        applyZoom(100, false); // Reset on mobile
    }
 });
 ```
 ### 3. Reset Button Green Indicator
 **Feature**: Reset button turns green when zoom ≠ 100%
 **Implementation**:
 ```javascript
 if (zoomValue !== 100) {
    resetBtn.classList.add('zoom-not-default');
 } else {
    resetBtn.classList.remove('zoom-not-default');
 }
 ```
 **CSS**:
 ```css
 .zoom-reset-btn.zoom-not-default:hover {
    background: rgba(39, 174, 96, 0.5); /* Green */
 }
 ```
 ### 4. Keyboard Shortcuts
 **Supported Shortcuts**:
 - `Ctrl/Cmd + Plus`: Zoom in (+10%)
 - `Ctrl/Cmd + Minus`: Zoom out (-10%)
 - `Ctrl/Cmd + 0`: Reset to 100%
 **Implementation**:
 ```javascript
 document.addEventListener('keydown', function(e) {
    if ((e.ctrlKey || e.metaKey) && !e.shiftKey) {
        if (e.key === '=' || e.key === '+') {
            e.preventDefault();
            incrementZoom(10);
        }
        // ... other shortcuts
    }
 });
 ```
 ## Bottom Scroll Detection Integration
 **Feature**: Info and back-to-top buttons turn green when at page bottom
 **Challenge**: Zoom affects scroll calculations
 **Solution**: Bottom detection works independently of zoom
 ```javascript
 const scrollHeight = document.documentElement.scrollHeight;
 const clientHeight = document.documentElement.clientHeight;
 const isAtBottom = (scrollHeight - currentScroll - clientHeight) < 50;
 ```
 **Why it works**: `scrollHeight` and `clientHeight` automatically account for zoomed content dimensions
 ## Future Considerations
 ### Potential Enhancements
 1. **Smooth Zoom Transitions**
   - Current: Instant zoom change
   - Possible: CSS transition on zoom property
   - Trade-off: May feel laggy for large zoom changes
 2. **Zoom Presets**
   - Current: Free-range slider
   - Possible: Preset buttons (50%, 75%, 100%, 125%, 150%)
   - Trade-off: Less flexible, but faster access
 3. **Per-Section Zoom**
   - Current: Entire document zooms
   - Possible: Zoom specific sections independently
   - Trade-off: Complex state management
 ### Known Limitations to Monitor
 1. **Firefox < 126**: No CSS zoom support (falls back to 100%)
 2. **Print Behavior**: Zoom is reset for print (intentional)
 3. **High Zoom Levels**: Text rendering quality may degrade > 175%
 ## Testing Checklist
 - [ ] Zoom in/out with slider
 - [ ] Zoom with keyboard shortcuts
 - [ ] Reset button functionality
 - [ ] Fixed elements stay constant size
 - [ ] Horizontal scroll appears when needed
 - [ ] Bottom detection works with zoom
 - [ ] Green button indicators work correctly
 - [ ] localStorage persistence works
 - [ ] Mobile: Zoom control hidden
 - [ ] Print: Zoom resets properly
 ## References
 - CSS zoom specification: [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/CSS/zoom)
 - Browser compatibility: [Can I Use - CSS zoom](https://caniuse.com/css-zoom)
 - Related: transform scale vs zoom discussion
 ---
 **Last Updated**: 2025-11-12
 **Author**: Development Team
 **Status**: Implemented and Stable