Part 1: Shared Utilities
- Create internal/fileutil package with FindDataFile() and LoadJSON()
- Create internal/lang package with language constants and validation
- Eliminate 46 lines of code duplication between cv/loader.go and ui/loader.go
- Simplify cv/loader.go from 69 to 36 lines (-48%)
- Simplify ui/loader.go from 56 to 24 lines (-57%)
Part 2: Validation Layer
- Add comprehensive validation in internal/models/cv/validation.go
- Validate Personal (name, email format, URLs)
- Validate Experience (required fields, dates)
- Validate Education (required fields)
- Validate Skills (proficiency ranges 1-5, categories)
- Validate Languages (proficiency levels 1-5)
- Validate Projects (title, URLs)
- Validate Meta (version, language)
- Integrate validation into LoadCV() - automatic on load
- Create ValidationError and ValidationErrors types for clear error reporting
- Report all validation errors at once (better UX)
Testing:
- Add comprehensive tests for fileutil package (FindDataFile, LoadJSON)
- Add tests for lang package (IsValid, Validate, All)
- Add 280+ validation test cases covering edge cases
- All tests pass with real CV data (cv-en.json, cv-es.json)
- Fixed validation to allow both URLs and local paths for gitRepoUrl
Documentation:
- Create _go-learning/refactorings/002-shared-utilities-validation.md
- Document architecture, benefits, testing, and interview talking points
- Explain WHY decisions were made (DRY, type safety, data integrity)
Benefits:
- DRY: Single source of truth for utilities
- Type safety: Language constants instead of magic strings
- Data integrity: Validation catches errors at load time
- Better errors: Clear messages showing all issues at once
- Maintainability: Centralized utilities easier to update
Updated --shadow-lg in light theme from harsh 2px 2px 9px to soft 0 4px 16px with reduced opacity (0.2). This provides a more professional, diffuse shadow that matches the quality of the dark theme.
- Center download button text with justify-content
- Set header text to solid black (#000) for better visibility
- Darken close button background for better contrast
- Remove any disabled appearance on mobile
Fixes grayed-out/disabled look and left-aligned button text on mobile.
- Hide subtitle on mobile to save vertical space
- Reduce all font sizes (header: 1.25rem, titles: 0.9rem, text: 0.75rem)
- Decrease modal padding from 2.5rem to 1.5rem 1rem
- Shrink page badges from 60×60px to 50×50px
- Reduce card padding from 16px to 12px
- Decrease gaps from 12px to 10px throughout
- Compact footer and button spacing
- Make download button smaller with 0.9rem font
Significantly reduces modal height for better mobile UX on small screens (iPhone 13 Mini, Samsung S24).
- Scale recommended card 12% larger on desktop for emphasis
- Add subtle golden border to Default CV (full opacity when selected)
- Pre-select Default CV by default with download button enabled
- Fix double border issue: exclude recommended card from red selection border
- Remove red focus outline for recommended card (transparent)
- Reduce modal height: thumbnail 280px→220px, padding 16px→12px
- Redesign mobile layout as compact button-style cards
- Hide full thumbnails on mobile, show page count badges instead
- Horizontal layout on mobile with left-aligned text
- Reduce mobile gap from 24px to 12px for better space efficiency
Improves visual hierarchy and mobile usability on small screens (iPhone 13 Mini, Samsung S24).
Simplified PDF download UX to use only the modal loading overlay,
removing the redundant toast notification that appeared when the modal
was closed during download. Updated tests to reflect the new behavior.
Changes:
- Removed toast trigger logic from PDF modal download function
- Removed modal close event listener for toast display
- Updated toast notification test expectations
- Fixed recommended card outline styling
Provides easy commands for different test scenarios:
- make test → Fast unit tests (CI-safe, no Chrome)
- make test-all → ALL tests including PDF/Chrome integration
- make test-integration → PDF tests only
- make lint → Run golangci-lint
- make check → Lint + unit tests
- make all → Everything (lint + all tests + build)
- Add '// +build integration' tag to exclude from default test runs
- CI runs fast unit tests only (no Chrome dependency)
- Full test suite available with: go test -tags=integration ./...
PDF tests require Chrome browser and are run manually before releases.
- Replace chromedp.Flag() with chromedp.NoSandbox
- Replace chromedp.Flag() with chromedp.DisableGPU
- Apply fix to both GenerateFromURL and GenerateFromURLWithOptions
- Fixes Ubuntu 23.10+ AppArmor sandbox restrictions
The chromedp.Flag() method wasn't properly disabling the sandbox, causing
Chrome to crash with 'No usable sandbox!' fatal error in CI.
Tests verify both light and dark theme patterns:
- Light: #d6d6d6 gray with concentric squares pattern
- Dark: #3a3a3a gray with diagonal green grid pattern
- Auto theme switches patterns based on system preference
- Pattern persistence when switching themes
- Visual screenshots for manual verification
All 5 tests passing ✅
Light theme:
- Change background from #b8bbbe to #d6d6d6 (light gray)
- Add concentric squares pattern with 4 gradient layers
- Creates subtle geometric texture on gray background
Dark theme:
- Change background from rgb(82, 86, 89) to #3a3a3a (medium gray)
- Add diagonal grid pattern with green glow (rgba(0, 255, 128, 0.15))
- 45deg and -45deg crosshatch creates retro tech aesthetic
Both patterns use CSS custom properties (--page-bg-pattern) and are
applied via background-image in _reset.css. Patterns are fixed and
maintain visibility across theme switches.
- Configure chromedp with headless mode and CI-friendly flags
- Add --no-sandbox flag (required for Docker/CI environments)
- Add --disable-gpu and --disable-dev-shm-usage for stability
- Use NewExecAllocator with DefaultExecAllocatorOptions
This fixes 'chrome failed to start' errors in GitHub Actions CI where
Chrome needs to run without a display and with relaxed sandbox restrictions.
- Add findDataFile() helper to search up directory tree for data files
- Fixes tests running from subdirectories (internal/handlers)
- Install Chrome in GitHub Actions for PDF generation tests
This resolves test failures that have existed since PDF tests were introduced:
- Error: 'open data/cv-es.json: no such file or directory'
- Error: 'chrome failed to start'
Tests now properly locate data files from any working directory and
have Chrome available for PDF generation in CI environment.
- Reorder cards: Short → Default ⭐ → Extended (was Short → Extended → Default)
- Add cleanup to prevent stuck blur effect on modal reopen
- Use MutationObserver to reset loading state when modal opens
- Add close event listener to clear loading-active class
Fixes:
1. Default CV now displays in center position as intended
2. Modal no longer shows grey/faded content due to stuck loading-active class
**TESTING** - These patterns can be easily reverted or modified
Light Theme (Woven Fabric Pattern):
- Subtle gray crosshatch pattern
- Multiple gradients creating woven texture
- Professional and clean appearance
Dark Theme (Diagonal Grid with Green Glow):
- 45° and -45° diagonal lines
- Green glow (rgba(0, 255, 128, 0.1))
- Cyberpunk/tech aesthetic
- 40px grid spacing
Implementation:
- Added --page-bg-pattern CSS variables to color-theme.css
- Applied patterns via body background-image in _reset.css
- OLD pattern commented out and preserved for easy restoration
- Patterns work with light, dark, and auto themes
Files changed:
- static/css/color-theme.css: Added pattern variables
- static/css/01-foundation/_reset.css: Applied patterns to body
To revert: Uncomment old pattern and remove --page-bg-pattern usage
**Test 3 Updated**: Shortcut URL behavior changed
- OLD: Expected HTTP 301 redirect to /export/pdf
- NEW: Expects HTTP 200 with direct PDF and Content-Disposition header
- Verifies correct filename: cv-jamr-2025-{lang}.pdf
**Test 6 Added**: Language switching links
- Tests "See this CV in Spanish/English" links
- Verifies URL correctness (/?lang=es and /?lang=en)
- Ensures no URL corruption from replaceYearPlaceholder fix
- Checks target="_blank" attribute
- Tests both English → Spanish and Spanish → English links
All 6 tests passing:
✅ EN Direct Shortcut URL
✅ ES Direct Shortcut URL
✅ Shortcut URL Direct Download (updated)
✅ Year Validation
✅ No JavaScript Required
✅ Language Switching Links (new)
**Issue 1: URL corruption in "See this CV in..." links**
- Bug: replaceYearPlaceholder used fmt.Sprintf on ALL URLs
- URLs like "/?lang=es" were corrupted to "/?lang=es%!(EXTRA string=2025)"
- Fix: Changed to strings.ReplaceAll("{{YEAR}}", year)
- Result: Only replaces actual {{YEAR}} placeholders, leaves other URLs intact
**Issue 2: Download filename not respected**
- Bug: Shortcut URLs (cv-jamr-2025-en.pdf) redirected with HTTP 301
- Browsers used original URL filename instead of Content-Disposition header
- Fix: Generate PDF directly in DefaultCVShortcut handler
- Result: Returns PDF with correct filename in Content-Disposition header
Files changed:
- internal/models/cv.go: Fixed replaceYearPlaceholder function
- internal/handlers/cv.go: Changed redirect to direct PDF generation
Both fixes verified:
- "See this CV in Spanish" link: href="/?lang=es" ✓
- Download link: filename=cv-jamr-2025-en.pdf ✓
UX Improvement:
- Added visual feedback during PDF generation process
- Users now see immediate response when clicking download button
- Clear communication about what's happening during the wait
New Features:
- Loading overlay with animated spinner
- Format-specific estimated generation times (Short: ~3s, Default: ~4s, Long: ~8s)
- Blur effect on modal background during loading
- Bilingual support (English/Spanish)
- Automatic modal close after download completes
CSS Updates (static/css/04-interactive/_modals.css):
- Added .pdf-loading-overlay with glassmorphism effect
- Spinning animation for loader (1s linear infinite)
- Fade-in animation (300ms)
- Accessibility: respects prefers-reduced-motion
- Background blur when loading active
HTML Updates (templates/partials/modals/pdf-modal.html):
- Loading overlay structure with spinner
- Dynamic loading messages based on selected format
- Enhanced downloadPDF() function with timing logic
Before: Click → silence → download appears
After: Click → overlay + spinner + estimate → download appears
## Documentation Updates (doc/11-PDF-EXPORT.md)
Added "References Section Integration" section with:
- Template code examples for shortcut URL usage
- Data configuration structure
- Key features and use cases
- Security attributes documentation
- Test command reference
## Test Updates (tests/mjs/28-references-pdf-download.test.mjs)
Completely rewrote test to match new direct link behavior:
- ❌ OLD: Tested modal opening, onclick handlers
- ✅ NEW: Tests direct shortcut URLs
New test coverage (5 tests):
1. English direct shortcut URL validation
2. Spanish direct shortcut URL validation
3. HTTP 301 redirect verification
4. Year validation (404 for invalid years)
5. Works without JavaScript (PDF export context)
Verifies:
- Correct href: /cv-jamr-{year}-{lang}.pdf
- No onclick handlers (pure HTML link)
- Security attributes (target="_blank", rel="noopener noreferrer")
- Year-aware dynamic URLs
- Language-aware (es/en)
- Backend 301 redirects working
- 404 for past/future years
## Benefits
- Comprehensive test coverage for new behavior
- Complete documentation with examples
- Easy to maintain and understand
- Validates entire shortcut URL feature end-to-end
## Problem
- References section PDF link opened modal dialog
- Modal doesn't work in PDF or non-browser environments
- Link was not usable when CV exported as PDF
## Solution
- Changed from `onclick="openPdfModal()"` to direct shortcut URL
- Spanish CV: `/cv-jamr-2025-es.pdf`
- English CV: `/cv-jamr-2025-en.pdf`
- Language-aware: Uses {{$.Lang}} template variable
- Year-aware: Uses {{$.CurrentYear}} for auto-updates
## Benefits
- ✅ Works in any environment (PDF, browser, external links)
- ✅ Direct download without JavaScript/modal
- ✅ Shareable, permanent URLs
- ✅ Auto-updates yearly with no code changes
Technical details:
- File: templates/partials/sections/references.html:16
- Uses shortcut URLs created in previous feature
- Maintains target="_blank" and security attributes
## Merged Content
- Merged LONG-PDF-GENERATION.md technical details into doc/11-PDF-EXPORT.md
- Removed duplicate documentation file
- Single source of truth for all PDF export documentation
## Added Technical Details
- PDF generation flow diagram
- 2-column vs 3-column layout architecture decision
- Sidebar width configuration guide (18%-30% analysis)
- Detailed CSS injection strategy with code examples
- HTML structure examples for page layouts
- Expanded compact sidebar fonts implementation details
- Font size breakdown table (2-6% reduction)
## Result
- Comprehensive PDF documentation: 966 lines (was 793)
- Added 173 lines of technical implementation details
- Removed 411-line duplicate file
- Better organized, single reference for developers and users
Benefits:
- Single source of truth for PDF features
- No duplication between docs
- Easier maintenance
- Complete technical and user-facing documentation in one place
## Shortcut URLs
- New routes: /cv-jamr-{year}-{lang}.pdf (e.g., /cv-jamr-2025-en.pdf)
- Year validation: Only current year accepted, returns 404 for past/future
- Auto-redirects (301) to: /export/pdf?lang={lang}&length=short&icons=show&version=with_skills
- Both languages supported: en and es
## PDF Modal Updates
- Replaced "Current View" option with "Default CV (Recommended)"
- Visual highlighting: purple gradient badge, star emoji ⭐, bold text
- Uses shortcut URL with dynamic year detection
- Clear recommendation for users (5 pages, short with skills)
## Technical Details
- Handler: DefaultCVShortcut() in internal/handlers/cv.go
- Pattern check in Home() handler for proper routing
- Helper function: window.openPdfModal() for references section
- Documentation: PDF-SHORTCUT-IMPLEMENTATION.md
Benefits:
- Memorable, shareable URLs (juan.andres.morenorub.io/cv-jamr-2025-en.pdf)
- Auto-updates yearly without code changes
- Clear user guidance for recommended CV format
Changed PDF filename format to use hyphens instead of underscores for
consistency with other filename components, while keeping API parameter
as `version=with_skills`.
## Changes
**Backend:**
- internal/handlers/cv.go: Add underscore-to-hyphen conversion in filename generation
- New logic: `strings.ReplaceAll(version, "_", "-")` for filename only
- API parameter unchanged: still accepts `version=with_skills`
**Tests:**
- internal/handlers/pdf_test.go: Update expected filenames to use hyphens
- cv-*-with_skills-*.pdf → cv-*-with-skills-*.pdf
**Documentation:**
- Updated all PDF filename references to use hyphens
- PDF-EXPORT-FEATURE.md
- doc/LONG-PDF-GENERATION.md
- PDF-VALIDATION-REPORT.md (new validation report)
**PDFs:**
- Regenerated all 8 PDFs with new naming convention
- Old: cv-short-with_skills-jamr-2025-en.pdf
- New: cv-short-with-skills-jamr-2025-en.pdf
## Examples
API calls unchanged:
- GET /export/pdf?version=with_skills (still works)
Generated filenames:
- cv-short-with-skills-jamr-2025-en.pdf ✓
- cv-long-with-skills-jamr-2025-es.pdf ✓
**Tests:** All passing ✓
**API:** Backwards compatible ✓
- Created keyboard._hs as reference documentation (inline handler in body tag)
- Externalized 9 hamburger menu navigation links to scrollToSection()
- Added scrollToSection() as JavaScript function (CSP-safe, no eval needed)
- Restored original keyboard handler format in body tag (working correctly)
- Removed problematic navigation._hs (had syntax/CSP issues)
- Added Rule 4 to HYPERSCRIPT-RULES.md on event handler externalization
- Updated PROJECT-MEMORY.md with externalization guidelines
Key learnings:
- Complex event handlers that inspect event properties must stay inline
- JavaScript functions avoid CSP unsafe-eval restrictions
- Navigation successfully externalized: 9 links → 1 function (91% reduction)
Changed PDF export naming convention from 'detailed' to 'short' for better clarity and contrast with 'extended'. Updated:
- Documentation: All references from 'detailed' → 'short'
- JSON data files: Static PDF URLs now use cv-short-jamr-{{YEAR}}-{lang}.pdf
- Frontend modal: Removed 'short' → 'detailed' mapping (now stays as 'short')
- Static PDFs: Renamed cv-detailed-* to cv-short-* (deleted old files)
- Backend validation: Change
- Changed from 24px back to 60px (matching projects structure)
- Used color: unset !important to reset CSS color override
- Allows inline color styles (style='color: #9333EA') to work
- Matches the project list icon styling exactly
- Reduced course responsibility icons to 24px (was 80px)
- Added color: inherit !important to try preserving inline color styles
- Removed borders, backgrounds, and padding for cleaner inline appearance
Note: color: inherit may inherit from parent theme color rather than
preserving individual icon colors. May need adjustment.
Removed overly broad selector that was shrinking ALL course
responsibility icons to 1.2em. Now only targets truly inline
icons within .course-desc text, not the main 60px list icons.
Problem: Inline icons embedded in responsibilities, courses, and
projects had explicit width='60' height='60' attributes that made
them too large (60px instead of ~16px).
Solution:
- Added CSS with !important to override inline width/height attributes
- Targeted inline icons in:
* Course responsibilities and descriptions
* Project descriptions and technologies
* Experience responsibilities (within divs)
- Preserved large icons (80px) for main company/course/project logos
Changes:
- static/css/03-components/_courses.css: Override to 1.2em
- static/css/03-components/_projects.css: Override to 1.2em
- static/css/03-components/_cv-section.css: Override to 1.2em
Test Results:
✅ 7 course inline icons: 16px × 16px
✅ Main company icons: 80px × 80px (preserved)
Calculation: #5e5e5e inverted = #a1a1a1
- Set LIV Golf border to #a1a1a1 in dark theme
- After invert(1) filter → appears as #5e5e5e (correct gray)
- Light theme: resets to normal var(--icon-border)
Filter inverts ENTIRE element including borders, so we
pre-compensate by using the inverse color.
- Changed from transparent to #5e5e5e (rgb(94,94,94))
- Visible but subtle medium gray border in dark theme
- Updated test to verify new border color
- Note: CSS filter on LIV Golf only affects image pixels, not border
- Changed from rgba(255,255,255,0.05) to 'transparent'
- Previous attempt used WHITE transparent which was still visible
- Now borders are rgba(0,0,0,0) - completely invisible
- Verified with Playwright test showing transparent borders
- All icons (OBS, LIV Golf, etc.) now have no visible borders
- Changed from #1e1e1e to rgba(255, 255, 255, 0.05)
- Borders now 95% transparent, virtually invisible
- Applies to ALL icon borders (OBS, LIV Golf, etc.)
- Invert filter remains ONLY for LIV Golf logo
- Changed --icon-border from #2a2a2a to #1e1e1e (rgb(30,30,30))
- Background is #1a1a1a (rgb(26,26,26)), only 4 RGB units difference
- Borders now barely visible, creating cleaner dark theme appearance
- Add --icon-border variable: #ddd (light) / #2a2a2a (dark)
- Add --item-separator variable: rgba(0,0,0,0.1) / rgba(255,255,255,0.05)
- Replace 6 hardcoded icon borders with var(--icon-border)
- Replace 3 hardcoded separators with var(--item-separator)
- Add CSS filter to invert LIV Golf logo in dark themes for visibility
- LIV Golf logo filter: invert(1) in dark/auto(dark), none in light
- Auto theme dark mode now uses #3a3d3e (matches explicit dark)
- Previously used #2a2a2a causing visible difference when switching
- Ensures only two visual states (light/dark) regardless of theme mode
Light theme sidebar:
- Background: #d1d4d2 (light gray)
- Text: dark colors
Dark theme sidebar:
- Background: #3a3d3e (darker gray, between page bg and content)
- Text: light colors (using CSS variables)
- Titles: light colors
Changes:
- Revert sidebar bg to use var(--sidebar-bg) for theme switching
- Update dark theme sidebar color to #3a3d3e
- Replace all hardcoded text colors with CSS variables
- Sidebar titles, content, and arrows now adapt to theme
Change sidebar background from var(--sidebar-bg) to fixed #d1d4d2
so it remains the same light gray color in both light and dark themes.
The sidebar should provide a consistent visual anchor regardless
of the main content theme.
juanatsap