juanatsap
925a95c1b4
- 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)
221 lines
7.4 KiB
Markdown
221 lines
7.4 KiB
Markdown
# 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">
|
|
```
|
|
|
|
### Rule 4: Event Handler Externalization Guidelines (2025-11-20)
|
|
**Know what CAN and CANNOT be externalized**
|
|
|
|
#### ✅ **CAN Be Externalized:**
|
|
**Simple function calls without complex event inspection:**
|
|
```html
|
|
<!-- Navigation handlers -->
|
|
<a href="#section" _="on click call scrollToSection(event, 'section')">
|
|
|
|
<!-- Toggle handlers -->
|
|
<input _="on change call toggleCVLength(my.checked)">
|
|
|
|
<!-- Hover handlers -->
|
|
<button _="on mouseenter call syncPdfHover(true)
|
|
on mouseleave call syncPdfHover(false)">
|
|
```
|
|
|
|
**External function example:**
|
|
```hyperscript
|
|
def scrollToSection(event, sectionId)
|
|
call event.preventDefault()
|
|
set element to document.getElementById(sectionId)
|
|
if element then call element.scrollIntoView({behavior: 'smooth'}) end
|
|
end
|
|
```
|
|
|
|
#### ❌ **MUST Stay Inline:**
|
|
**Complex event handlers that inspect event properties:**
|
|
```html
|
|
<!-- Keyboard handlers with event.key, event.target inspection -->
|
|
<body _="on keydown
|
|
set tagName to event.target.tagName
|
|
set isInputField to (tagName is 'INPUT' or tagName is 'TEXTAREA')
|
|
if event.key is 'l' and not event.ctrlKey and not isInputField
|
|
halt the event
|
|
-- handler logic here
|
|
end
|
|
end">
|
|
```
|
|
|
|
**Why:** The `event` variable in `_=""` attributes is a hyperscript runtime variable. External `def` functions don't have direct access to this event context, causing scoping issues.
|
|
|
|
#### 🎯 **Optimization for Inline Handlers:**
|
|
**Use `then` chains to make inline code more compact:**
|
|
|
|
```hyperscript
|
|
-- Before (verbose)
|
|
if condition
|
|
do step1
|
|
do step2
|
|
do step3
|
|
end
|
|
|
|
-- After (compact with then chains)
|
|
if condition
|
|
do step1 then do step2 then do step3
|
|
end
|
|
```
|
|
|
|
**Example from body keyboard handler:**
|
|
```html
|
|
if event.key is '?' and not event.ctrlKey and not event.metaKey and not event.altKey and not isInputField
|
|
halt the event then set modal to #shortcuts-modal then if modal then call modal.showModal() end
|
|
end
|
|
```
|
|
|
|
## File Organization
|
|
|
|
```
|
|
static/hyperscript/
|
|
├── utils._hs → Core utilities (scroll, print, etc.)
|
|
├── toggles._hs → Toggle functions (CV length, icons, theme)
|
|
├── hover-sync._hs → Hover sync functions (PDF, print, zoom)
|
|
├── navigation._hs → Navigation functions (scroll-to-section) [2025-11-20]
|
|
└── keyboard._hs → Keyboard handler reference (inline in body tag)
|
|
```
|
|
|
|
### Load Order in templates/index.html:
|
|
```html
|
|
<script type="text/hyperscript" src="/static/hyperscript/utils._hs"></script>
|
|
<script type="text/hyperscript" src="/static/hyperscript/toggles._hs"></script>
|
|
<script type="text/hyperscript" src="/static/hyperscript/hover-sync._hs"></script>
|
|
<script type="text/hyperscript" src="/static/hyperscript/keyboard._hs"></script>
|
|
<script type="text/hyperscript" src="/static/hyperscript/navigation._hs"></script>
|
|
<script src="https://unpkg.com/hyperscript.org@0.9.14"></script>
|
|
```
|
|
|
|
## Required Functions
|
|
|
|
### Core Functions (utils._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-sync._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
|
|
|
|
### Navigation Functions (navigation._hs) [2025-11-20]
|
|
1. `scrollToSection(event, sectionId)` - Smooth scroll to CV section
|
|
|
|
## 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
|
|
|
|
---
|
|
|
|
## Recent Changes
|
|
|
|
### 2025-11-20: Event Handler Externalization Guidelines
|
|
- ✅ Added Rule 4: Clear guidelines on what can/cannot be externalized
|
|
- ✅ Navigation handlers successfully externalized (9 links → 1 function)
|
|
- ✅ Documented `then` chain optimization for inline handlers
|
|
- ✅ Updated file organization with navigation._hs
|
|
- ⚠️ Keyboard handlers documented to stay inline (event context requirement)
|
|
|
|
---
|
|
|
|
**Last Updated**: 2025-11-20
|
|
**Hyperscript Version**: 0.9.14+
|
|
**Status**: MANDATORY - ALWAYS FOLLOW
|