Files

T

juanatsap 925a95c1b4 refactor: externalize navigation handlers and fix hyperscript syntax errors

- 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)

2025-11-20 09:46:06 +00:00

7.4 KiB

Raw Blame History

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">

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:

<!-- 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:

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:

<!-- 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:

-- 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:

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:

<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)

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

Toggle Functions (toggles._hs)

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

Hover Sync Functions (hover-sync._hs)

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

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

Check browser console for parse errors
Verify all functions are defined (no "X is null" errors)
Test all toggles work correctly
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

7.4 KiB Raw Blame History