cv-site/doc/4-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:
```html
<input type="checkbox"
       id="lengthToggle"
       _="on change call toggleCVLength(my.checked)">
```

❌ **BAD** - Inline logic nightmare:
```html
<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:
```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