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 - Organized by Category

✅ NO def statement limit with latest hyperscript!

HISTORICAL NOTE (2025-11-17): Hyperscript 0.9.12 had a 3 def limit. Latest version REMOVED this limitation.

• Test verification: tests/mjs/9-hyperscript-def-limit.test.mjs (all 5 def statements passed)
• Migration in progress: Moving functions from JavaScript back to hyperscript

Current Best Practice: Organize hyperscript functions by category in separate files

static/hyperscript/
├── toggles._hs        # Toggle functions (CV length, icons, theme)
├── hover-sync._hs     # Hover synchronization functions
├── utils._hs          # Utility functions (print, scroll, etc.)
└── keyboard._hs       # Keyboard shortcut handlers

Benefits of Hyperscript Organization:

• ✅ Clean separation of concerns
• ✅ Easy to locate and maintain functions
• ✅ No artificial limitations
• ✅ Server-side hypermedia pattern (functions loaded with HTML)
• ✅ Still callable from anywhere using call functionName(args)

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