cv-site/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:
```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