cv-site/doc/HYPERSCRIPT-RULES.md

Hyperscript Development Rules

MANDATORY RULES - ALWAYS FOLLOW

Rule 1: Code Cleanliness

More than 3 lines of hyperscript → Move to function in file

• Inline hyperscript in HTML should be kept minimal (≤3 lines)
• Longer logic MUST be extracted to named functions in ._hs files
• HTML templates should be clean and readable

Rule 2: File Structure - Hyperscript 0.9.12 Limitation

Maximum 3 def statements TOTAL across ALL files

⚠️ CRITICAL: Hyperscript 0.9.12 has a parser limitation - more than 3 def statements across ALL loaded ._hs files causes:

Error: Expected 'end' but found 'def'

Solution for Global Reusable Functions: Use regular JavaScript instead

• static/js/cv-functions.js - Global toggle and utility functions
  • toggleCVLength(), toggleIcons(), toggleTheme()
  • syncPdfHover(), syncPrintHover(), highlightZoomControl()

Solution for Hyperscript-Specific Logic: Keep max 3 defs

• static/hyperscript/functions._hs - ONLY hyperscript-specific utilities (printFriendly, initScrollBehavior, handleScroll)

Why JavaScript for Global Functions:

• ✅ No artificial limits
• ✅ Better performance (native JS)
• ✅ Better debugging
• ✅ Can still be called from hyperscript using call toggleIcons(my.checked)

Rule 3: HTML Structure Cleanliness

HTML must be as clean as possible regarding hyperscript

✅ GOOD - Clean, readable:

<input type="checkbox"
       id="lengthToggle"
       _="on change call toggleCVLength(my.checked)">

❌ BAD - Inline logic nightmare:

<input type="checkbox"
       id="lengthToggle"
       _="on change
            if my.checked
              remove .cv-short from .cv-paper
              add .cv-long to .cv-paper
              set localStorage['cv-length'] to 'long'
              set #lengthToggleMenu's checked to true
            else
              remove .cv-long from .cv-paper
              add .cv-short to .cv-paper
              set localStorage['cv-length'] to 'short'
              set #lengthToggleMenu's checked to false
            end">

File Organization

static/hyperscript/
├── functions._hs   → Core utilities (3 defs max)
├── toggles._hs     → Toggle functions (3 defs max)
└── hover._hs       → Hover sync functions (3 defs max)

Load Order in templates/index.html:

<script type="text/hyperscript" src="/static/hyperscript/functions._hs"></script>
<script type="text/hyperscript" src="/static/hyperscript/toggles._hs"></script>
<script type="text/hyperscript" src="/static/hyperscript/hover._hs"></script>
<script src="https://unpkg.com/hyperscript.org@0.9.12"></script>

Required Functions

Core Functions (functions._hs)

1. printFriendly() - Handle print-friendly view
2. initScrollBehavior() - Initialize scroll variables
3. handleScroll() - Manage scroll behavior and fixed button positioning

Toggle Functions (toggles._hs)

1. toggleCVLength(isLong) - Switch between short/long CV
2. toggleIcons(showIcons) - Show/hide icons
3. toggleTheme(isClean) - Switch between default/clean theme

Hover Sync Functions (hover._hs)

1. syncPdfHover(show) - Sync hover state across PDF buttons
2. syncPrintHover(show) - Sync hover state across print buttons
3. highlightZoomControl(show) - Highlight zoom control on hover

Why These Rules Exist

Maintainability

• Functions with descriptive names are self-documenting
• Easier to test and debug
• Changes in one place instead of scattered across templates

Performance

• Browser caches ._hs files
• Reduces HTML payload size
• Cleaner separation of concerns

Hyperscript 0.9.12 Limitation

• Parser breaks with >3 def in single file
• MUST split into multiple files
• Each file: ≤3 def statements

Common Mistakes to Avoid

❌ DON'T: Put all functions in one file if you have >3 defs ❌ DON'T: Write long inline hyperscript in HTML ❌ DON'T: Delete functions to work around the 3-def limit

✅ DO: Split functions across multiple ._hs files ✅ DO: Keep HTML clean with function calls ✅ DO: Maintain all required functions for clean architecture

Testing After Changes

1. Check browser console for parse errors
2. Verify all functions are defined (no "X is null" errors)
3. Test all toggles work correctly
4. Hard refresh browser (Ctrl+Shift+R) to clear cache

---

Last Updated: 2025-01-17 Hyperscript Version: 0.9.12 Status: MANDATORY - ALWAYS FOLLOW