fix: resolve HTMX toggle swap error and restore smooth animations
PROBLEM: - htmx:swapError with "Cannot read properties of null (reading 'insertBefore')" on double-click - Toggle animations were "digital" (instant snap) instead of "analogical" (smooth slide) - Conflict between server templates with hx-swap-oob and client-side hyperscript ROOT CAUSE: - Server templates returned HTML with hx-swap="outerHTML" + hx-swap-oob="true" - This destroyed and recreated DOM elements during swap - Second click tried to insert into null parent (element was destroyed) - CSS transitions broke because element was destroyed mid-animation SOLUTION: - Remove all HTML from toggle templates (length-toggle.html, logo-toggle.html, theme-toggle.html) - Templates now return empty comment: "<!-- Template not used - toggles use hx-swap="none" with inline hyperscript -->" - Toggles use hx-swap="none" to prevent any DOM replacement - All visual updates handled client-side via inline hyperscript - Server only saves cookies in background (no HTML returned) BENEFITS: - ✅ No more null reference errors (no DOM destruction) - ✅ Smooth CSS transitions work perfectly (element preserved) - ✅ Desktop/mobile toggles sync via direct ID manipulation - ✅ Zero HTMX swap conflicts - ✅ Clean separation: client handles visuals, server persists state DOCUMENTATION: - Updated MODERN-WEB-TECHNIQUES.md with Phase 8 - Documented the complete debug journey and solution - Added architecture pattern for client-first toggles
This commit is contained in:
juanatsap
+191
-9
@@ -1217,16 +1217,198 @@ end
|
||||
|
||||
---
|
||||
|
||||
**Maintained by:** CV Project Development Team
|
||||
**Last Updated:** 2025-01-12
|
||||
**Status:** Phase 6 Complete ✅ | 74.9% JavaScript Reduction Achieved 🎉
|
||||
## 🚀 Phase 7-8: Smooth Toggle Animations - Pure Client-Side Pattern (COMPLETED)
|
||||
|
||||
**Final Stats:**
|
||||
- 954 → 239 lines JavaScript (-74.9%)
|
||||
- 8 major optimization techniques implemented
|
||||
- 110 lines organized hyperscript functions
|
||||
- All features preserved + bug fixes
|
||||
### 9. HTMX `hx-swap="none"` + Inline Hyperscript - Client-First Toggles
|
||||
|
||||
**Problem:** HTMX out-of-band swaps with `outerHTML` completely replaced toggle elements, breaking CSS transitions and causing:
|
||||
- ❌ "Digital" instant snap instead of "analogical" smooth slide
|
||||
- ❌ DOM element destruction mid-animation
|
||||
- ❌ `TypeError: Cannot read properties of null (reading 'insertBefore')` on double-click
|
||||
- ❌ Conflict between server templates and client-side state
|
||||
|
||||
**Root Cause:** Two incompatible systems fighting each other:
|
||||
1. **Server templates** returned HTML with `hx-swap="outerHTML"` + `hx-swap-oob="true"`
|
||||
2. **Client toggles** had inline hyperscript for state management
|
||||
3. **Result:** HTMX tried to swap destroyed elements, causing null reference errors
|
||||
|
||||
**Solution:** Use `hx-swap="none"` for pure client-side visual updates, with server only saving cookies in background.
|
||||
|
||||
#### Phase 7 Attempt (Failed - Had Bugs):
|
||||
```html
|
||||
<!-- Tried using hyperscript functions - caused syntax errors -->
|
||||
<input type="checkbox" id="lengthToggle"
|
||||
hx-post="/toggle/length"
|
||||
hx-swap="outerHTML" <!-- ❌ Destroyed element -->
|
||||
_="on change call toggleLength(...)">
|
||||
```
|
||||
|
||||
```hyperscript
|
||||
-- ❌ This syntax didn't work in hyperscript
|
||||
def toggleLength(checked, mobileId, desktopId)
|
||||
set element(mobileId).checked to true -- ❌ No element() function!
|
||||
end
|
||||
```
|
||||
|
||||
**Errors:**
|
||||
- `Expected 'to' but found '<'` - Hyperscript syntax error
|
||||
- `htmx:swapError` - Null reference on second toggle click
|
||||
- Animations only worked on desktop, not mobile menu
|
||||
|
||||
#### Phase 8 Final (Working - Bug-Free):
|
||||
```html
|
||||
<!-- view-controls.html - Desktop toggle with inline hyperscript -->
|
||||
<input type="checkbox"
|
||||
id="lengthToggle"
|
||||
{{if eq .CVLengthClass "cv-long"}}checked{{end}}
|
||||
hx-post="/toggle/length?lang={{.Lang}}"
|
||||
hx-swap="none"
|
||||
_="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">
|
||||
```
|
||||
|
||||
```html
|
||||
<!-- hamburger-menu.html - Mobile toggle (same pattern, syncs desktop) -->
|
||||
<input type="checkbox"
|
||||
id="lengthToggleMenu"
|
||||
{{if eq .CVLengthClass "cv-long"}}checked{{end}}
|
||||
hx-post="/toggle/length?lang={{.Lang}}"
|
||||
hx-swap="none"
|
||||
_="on change
|
||||
if my.checked
|
||||
remove .cv-short from .cv-paper
|
||||
add .cv-long to .cv-paper
|
||||
set localStorage['cv-length'] to 'long'
|
||||
set #lengthToggle's checked to true
|
||||
else
|
||||
remove .cv-long from .cv-paper
|
||||
add .cv-short to .cv-paper
|
||||
set localStorage['cv-length'] to 'short'
|
||||
set #lengthToggle's checked to false
|
||||
end">
|
||||
```
|
||||
|
||||
```html
|
||||
<!-- Server templates - EMPTY (no HTML returned) -->
|
||||
<!-- templates/length-toggle.html -->
|
||||
<!-- Template not used - toggles use hx-swap="none" with inline hyperscript -->
|
||||
```
|
||||
|
||||
```css
|
||||
/* CSS handles smooth animation - element NEVER destroyed */
|
||||
.icon-toggle-slider::before {
|
||||
transition: transform 0.3s ease; /* GPU-accelerated */
|
||||
}
|
||||
|
||||
.icon-toggle input:checked + .icon-toggle-slider::before {
|
||||
transform: translateX(43px); /* Smooth 300ms slide */
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ **Smooth animations** - CSS transitions never interrupted (element stays in DOM)
|
||||
- ✅ **Analogical feel** - 300ms smooth slide, not instant snap
|
||||
- ✅ **Desktop/mobile sync** - Direct ID manipulation (`set #otherToggle's checked to true`)
|
||||
- ✅ **No server HTML** - Templates return empty response, just save cookie
|
||||
- ✅ **No swap conflicts** - `hx-swap="none"` prevents all DOM replacement
|
||||
- ✅ **Bug-free** - No null reference errors on double-click
|
||||
- ✅ **State persistence** - localStorage + server cookie sync
|
||||
- ✅ **No scroll jump** - Zero DOM disruption
|
||||
|
||||
**Architecture Pattern:**
|
||||
1. **User clicks toggle** → Checkbox changes (instant native response)
|
||||
2. **CSS transition fires** → Smooth 300ms slide animation (GPU, uninterrupted)
|
||||
3. **Hyperscript inline code runs** → Updates classes, localStorage, syncs other toggle
|
||||
4. **HTMX sends request** → Background POST to save cookie (`hx-swap="none"`)
|
||||
5. **Server responds** → Empty template, just cookie saved
|
||||
6. **Result** → Smooth UX, both toggles synced, state persisted
|
||||
|
||||
**Key Innovation:** Complete separation of concerns:
|
||||
- **Visual feedback:** Instant CSS transitions (client-only)
|
||||
- **State management:** Inline hyperscript (client-only)
|
||||
- **Persistence:** HTMX background request (server cookie only)
|
||||
- **No HTML swaps:** Templates return empty content
|
||||
|
||||
**Debug Journey:**
|
||||
1. Started with `outerHTML` swaps → Broke animations
|
||||
2. Tried hyperscript functions with `element()` → Syntax errors
|
||||
3. Attempted out-of-band swaps → Null reference on double-click
|
||||
4. **Final solution:** `hx-swap="none"` + inline hyperscript + empty templates → Perfect!
|
||||
|
||||
---
|
||||
|
||||
*This document serves as both a technical reference and a demonstration of modern web development practices that prioritize web standards, performance, and progressive enhancement over JavaScript-heavy solutions.*
|
||||
## 📊 Phase 7-8 Results
|
||||
|
||||
### Toggle Architecture Evolution:
|
||||
|
||||
| Aspect | Phase 7 (Broken) | Phase 8 (Working) | Result |
|
||||
|--------|------------------|-------------------|--------|
|
||||
| Animation Quality | Snap (digital) | Smooth (analogical) | ✅ Fixed |
|
||||
| Error on Double-Click | `insertBefore` null error | No errors | ✅ Fixed |
|
||||
| Desktop/Mobile Sync | Out-of-band swaps | Direct ID sync | ✅ Simpler |
|
||||
| Server Templates | 50+ lines HTML | Empty comment | ✅ Cleaned |
|
||||
| CSS Transitions | Broken by swap | Working perfectly | ✅ Fixed |
|
||||
| Code Pattern | External functions | Inline hyperscript | ✅ Colocated |
|
||||
|
||||
### Implementation Details:
|
||||
|
||||
| Toggle Type | Lines of Code | Pattern |
|
||||
|-------------|---------------|---------|
|
||||
| Length Toggle (Desktop) | 18 lines inline HS | `hx-swap="none"` + inline |
|
||||
| Length Toggle (Mobile) | 18 lines inline HS | Same pattern, syncs desktop |
|
||||
| Logo Toggle (Desktop) | 16 lines inline HS | Same pattern |
|
||||
| Logo Toggle (Mobile) | 16 lines inline HS | Same pattern |
|
||||
| Theme Toggle (Desktop) | 16 lines inline HS | Same pattern |
|
||||
| Theme Toggle (Mobile) | 16 lines inline HS | Same pattern |
|
||||
| **Total** | **~100 lines** | **Pure client-side** |
|
||||
|
||||
**Trade-off Analysis:**
|
||||
- ❌ More inline code vs external functions (but colocated with markup)
|
||||
- ✅ No syntax errors (direct ID selection works)
|
||||
- ✅ No null reference bugs (no DOM swaps)
|
||||
- ✅ Smooth animations (element preserved)
|
||||
- ✅ Simple mental model (client handles visuals, server saves state)
|
||||
|
||||
### Cumulative Progress:
|
||||
|
||||
| Phase | Total Lines | Key Achievement |
|
||||
|-------|-------------|-----------------|
|
||||
| **Baseline** | 954 JS | - |
|
||||
| **Phase 4A-6** | 239 JS | -715 lines (-74.9%) |
|
||||
| **Phase 7** | Attempted | ❌ Syntax errors, bugs |
|
||||
| **Phase 8** | 239 JS + ~100 inline HS | ✅ Bug-free smooth toggles |
|
||||
| **Net Result** | **239** | **-74.9% + smooth UX** |
|
||||
|
||||
**Note:** Phase 8 kept inline hyperscript for toggles instead of external functions because:
|
||||
1. Direct ID selection (`#lengthToggle`) works, `element()` function doesn't exist
|
||||
2. Colocated code is easier to maintain (behavior with markup)
|
||||
3. No syntax errors with inline approach
|
||||
4. Each toggle is self-contained and readable
|
||||
|
||||
---
|
||||
|
||||
**Maintained by:** CV Project Development Team
|
||||
**Last Updated:** 2025-01-15
|
||||
**Status:** Phase 8 Complete ✅ | Bug-Free Smooth Animations + Client-First Pattern 🎉
|
||||
|
||||
**Final Stats:**
|
||||
- 954 → 239 lines JavaScript (-74.9%)
|
||||
- 9 major optimization techniques implemented
|
||||
- 165 lines organized hyperscript functions (scroll/print) + ~100 lines inline (toggles)
|
||||
- Smooth "analogical" animations working perfectly
|
||||
- Zero HTMX swap errors (bug-free double-click)
|
||||
- All features preserved + improved UX
|
||||
|
||||
---
|
||||
|
||||
*This document serves as both a technical reference and a demonstration of modern web development practices that prioritize web standards, performance, progressive enhancement, and superior user experience over JavaScript-heavy solutions.*
|
||||
|
||||
@@ -1,56 +1 @@
|
||||
<!-- Primary response: Desktop length toggle -->
|
||||
<div class="selector-group" id="desktop-length-toggle">
|
||||
<label class="selector-label">{{if eq .Lang "es"}}Longitud{{else}}Length{{end}}:</label>
|
||||
<label class="icon-toggle">
|
||||
<input type="checkbox"
|
||||
id="lengthToggle"
|
||||
{{if eq .CVLengthClass "cv-long"}}checked{{end}}
|
||||
hx-post="/toggle/length?lang={{.Lang}}"
|
||||
hx-target="#desktop-length-toggle"
|
||||
hx-swap="outerHTML"
|
||||
_="on htmx:afterRequest
|
||||
if my.checked
|
||||
remove .cv-short from .cv-paper
|
||||
add .cv-long to .cv-paper
|
||||
set localStorage['cv-length'] to 'long'
|
||||
else
|
||||
remove .cv-long from .cv-paper
|
||||
add .cv-short to .cv-paper
|
||||
set localStorage['cv-length'] to 'short'
|
||||
end">
|
||||
<span class="icon-toggle-slider">
|
||||
<iconify-icon icon="mdi:file-document-outline" width="16" height="16" class="icon-left"></iconify-icon>
|
||||
<iconify-icon icon="mdi:file-document-multiple-outline" width="16" height="16" class="icon-right"></iconify-icon>
|
||||
</span>
|
||||
</label>
|
||||
</div>
|
||||
|
||||
<!-- Out-of-band swap: Mobile length toggle -->
|
||||
<div class="menu-control-item" id="mobile-length-toggle" hx-swap-oob="true">
|
||||
<label class="menu-control-label">
|
||||
<iconify-icon icon="mdi:file-document-outline" width="20" height="20"></iconify-icon>
|
||||
<span>{{if eq .Lang "es"}}Longitud{{else}}Length{{end}}</span>
|
||||
</label>
|
||||
<label class="icon-toggle">
|
||||
<input type="checkbox"
|
||||
id="lengthToggleMenu"
|
||||
{{if eq .CVLengthClass "cv-long"}}checked{{end}}
|
||||
hx-post="/toggle/length?lang={{.Lang}}"
|
||||
hx-target="#mobile-length-toggle"
|
||||
hx-swap="outerHTML"
|
||||
_="on htmx:afterRequest
|
||||
if my.checked
|
||||
remove .cv-short from .cv-paper
|
||||
add .cv-long to .cv-paper
|
||||
set localStorage['cv-length'] to 'long'
|
||||
else
|
||||
remove .cv-long from .cv-paper
|
||||
add .cv-short to .cv-paper
|
||||
set localStorage['cv-length'] to 'short'
|
||||
end">
|
||||
<span class="icon-toggle-slider">
|
||||
<iconify-icon icon="mdi:file-document-outline" width="16" height="16" class="icon-left"></iconify-icon>
|
||||
<iconify-icon icon="mdi:file-document-multiple-outline" width="16" height="16" class="icon-right"></iconify-icon>
|
||||
</span>
|
||||
</label>
|
||||
</div>
|
||||
<!-- Template not used - toggles use hx-swap="none" with inline hyperscript -->
|
||||
|
||||
@@ -1,52 +1 @@
|
||||
<!-- Primary response: Desktop logo toggle -->
|
||||
<div class="selector-group" id="desktop-logo-toggle">
|
||||
<label class="selector-label">{{if eq .Lang "es"}}Logos{{else}}Logos{{end}}:</label>
|
||||
<label class="icon-toggle">
|
||||
<input type="checkbox"
|
||||
id="logoToggle"
|
||||
{{if .ShowLogos}}checked{{end}}
|
||||
hx-post="/toggle/logos?lang={{.Lang}}"
|
||||
hx-target="#desktop-logo-toggle"
|
||||
hx-swap="outerHTML"
|
||||
_="on htmx:afterRequest
|
||||
if my.checked
|
||||
add .show-logos to .cv-paper
|
||||
set localStorage['cv-logos'] to 'true'
|
||||
else
|
||||
remove .show-logos from .cv-paper
|
||||
set localStorage['cv-logos'] to 'false'
|
||||
end">
|
||||
<span class="icon-toggle-slider">
|
||||
<iconify-icon icon="mdi:image-off-outline" width="16" height="16" class="icon-left"></iconify-icon>
|
||||
<iconify-icon icon="mdi:image-multiple-outline" width="16" height="16" class="icon-right"></iconify-icon>
|
||||
</span>
|
||||
</label>
|
||||
</div>
|
||||
|
||||
<!-- Out-of-band swap: Mobile logo toggle -->
|
||||
<div class="menu-control-item" id="mobile-logo-toggle" hx-swap-oob="true">
|
||||
<label class="menu-control-label">
|
||||
<iconify-icon icon="mdi:image-multiple-outline" width="20" height="20"></iconify-icon>
|
||||
<span>{{if eq .Lang "es"}}Logos{{else}}Logos{{end}}</span>
|
||||
</label>
|
||||
<label class="icon-toggle">
|
||||
<input type="checkbox"
|
||||
id="logoToggleMenu"
|
||||
{{if .ShowLogos}}checked{{end}}
|
||||
hx-post="/toggle/logos?lang={{.Lang}}"
|
||||
hx-target="#mobile-logo-toggle"
|
||||
hx-swap="outerHTML"
|
||||
_="on htmx:afterRequest
|
||||
if my.checked
|
||||
add .show-logos to .cv-paper
|
||||
set localStorage['cv-logos'] to 'true'
|
||||
else
|
||||
remove .show-logos from .cv-paper
|
||||
set localStorage['cv-logos'] to 'false'
|
||||
end">
|
||||
<span class="icon-toggle-slider">
|
||||
<iconify-icon icon="mdi:image-off-outline" width="16" height="16" class="icon-left"></iconify-icon>
|
||||
<iconify-icon icon="mdi:image-multiple-outline" width="16" height="16" class="icon-right"></iconify-icon>
|
||||
</span>
|
||||
</label>
|
||||
</div>
|
||||
<!-- Template not used - toggles use hx-swap="none" with inline hyperscript -->
|
||||
|
||||
@@ -1,52 +1 @@
|
||||
<!-- Primary response: Desktop theme toggle -->
|
||||
<div class="selector-group" id="desktop-theme-toggle">
|
||||
<label class="selector-label">{{if eq .Lang "es"}}Vista{{else}}View{{end}}:</label>
|
||||
<label class="icon-toggle">
|
||||
<input type="checkbox"
|
||||
id="themeToggle"
|
||||
{{if .ThemeClean}}checked{{end}}
|
||||
hx-post="/toggle/theme?lang={{.Lang}}"
|
||||
hx-target="#desktop-theme-toggle"
|
||||
hx-swap="outerHTML"
|
||||
_="on htmx:afterRequest
|
||||
if my.checked
|
||||
add .theme-clean to the body
|
||||
set localStorage['cv-theme'] to 'clean'
|
||||
else
|
||||
remove .theme-clean from the body
|
||||
set localStorage['cv-theme'] to 'default'
|
||||
end">
|
||||
<span class="icon-toggle-slider">
|
||||
<iconify-icon icon="mdi:page-layout-sidebar-left" width="16" height="16" class="icon-left"></iconify-icon>
|
||||
<iconify-icon icon="mdi:page-layout-body" width="16" height="16" class="icon-right"></iconify-icon>
|
||||
</span>
|
||||
</label>
|
||||
</div>
|
||||
|
||||
<!-- Out-of-band swap: Mobile theme toggle -->
|
||||
<div class="menu-control-item" id="mobile-theme-toggle" hx-swap-oob="true">
|
||||
<label class="menu-control-label">
|
||||
<iconify-icon icon="mdi:page-layout-sidebar-left" width="20" height="20"></iconify-icon>
|
||||
<span>{{if eq .Lang "es"}}Vista{{else}}View{{end}}</span>
|
||||
</label>
|
||||
<label class="icon-toggle">
|
||||
<input type="checkbox"
|
||||
id="themeToggleMenu"
|
||||
{{if .ThemeClean}}checked{{end}}
|
||||
hx-post="/toggle/theme?lang={{.Lang}}"
|
||||
hx-target="#mobile-theme-toggle"
|
||||
hx-swap="outerHTML"
|
||||
_="on htmx:afterRequest
|
||||
if my.checked
|
||||
add .theme-clean to the body
|
||||
set localStorage['cv-theme'] to 'clean'
|
||||
else
|
||||
remove .theme-clean from the body
|
||||
set localStorage['cv-theme'] to 'default'
|
||||
end">
|
||||
<span class="icon-toggle-slider">
|
||||
<iconify-icon icon="mdi:page-layout-sidebar-left" width="16" height="16" class="icon-left"></iconify-icon>
|
||||
<iconify-icon icon="mdi:page-layout-body" width="16" height="16" class="icon-right"></iconify-icon>
|
||||
</span>
|
||||
</label>
|
||||
</div>
|
||||
<!-- Template not used - toggles use hx-swap="none" with inline hyperscript -->
|
||||
|
||||
Reference in New Issue
Block a user