diff --git a/doc/MODERN-WEB-TECHNIQUES.md b/doc/MODERN-WEB-TECHNIQUES.md index a0c1eed..f73cec7 100644 --- a/doc/MODERN-WEB-TECHNIQUES.md +++ b/doc/MODERN-WEB-TECHNIQUES.md @@ -555,27 +555,139 @@ html {
New Content
``` +### Advanced Swap Timing + +```html + + +``` + +**Swap Timing Modifiers:** +- `swap:250ms` - Delay before old content removed (allows fade-out animation) +- `settle:250ms` - Delay before new content settled (allows fade-in animation) +- Combined: Smooth 500ms total transition (250ms fade-out + 250ms fade-in) + +**Use Cases:** +- Language switching with skeleton loaders +- Content transitions requiring smooth animations +- Coordinating multiple UI updates + +### Out-of-Band Swaps (Multi-Target Updates) + +**Problem:** Single request needs to update multiple page areas simultaneously. + +**Solution:** Use `hx-swap-oob` attribute for atomic multi-target updates. + +```html + + +
+

New Main Content

+
+ + +
5
+
+ Premium +
+``` + +**Key Points:** +- Main target replaced normally +- OOB elements updated by matching `id` attributes +- All updates happen atomically (single DOM transaction) +- Prevents multiple server requests +- Maintains consistency across UI + +**Real Example (Language Switch):** +```html + + +
+ +
+ + +
+ + +
+``` + +**Benefits:** +- ✅ Single server round-trip +- ✅ Atomic updates (no inconsistent intermediate states) +- ✅ Reduced network overhead +- ✅ Simpler client-side logic + +### History Management + +```html + + + + + +``` + +**Use Cases:** +- SPA-like navigation without full page reloads +- Shareable URLs for dynamic content +- Back/forward button support +- Deep linking into application state + +**Real Example (Language Switching):** +```html + +``` + +**Result:** URL changes to `/?lang=es`, shareable link, back button works. + ### Loading States ```html - - -
Loading...
``` ```css /* HTMX adds .htmx-request class automatically */ .htmx-indicator { - display: none; + opacity: 0; + transition: opacity 200ms ease-in; } .htmx-request .htmx-indicator { - display: inline-block; + opacity: 1; } ``` +**Advanced Pattern:** External indicators prevent destruction during swaps. See **Section 10: HTMX Loading Indicators** for comprehensive implementation. + ### Error Handling ```javascript @@ -1049,6 +1161,122 @@ def printFriendly() end ``` +#### Hover Synchronization Pattern + +**Problem:** Action bar and hamburger menu have duplicate buttons (PDF, Print, Zoom). When user hovers over one, the corresponding button in the other UI should also highlight for visual coherence. + +**Challenge:** JavaScript `mouseenter`/`mouseleave` events can't directly manipulate hyperscript functions from inline attributes. + +**Solution:** JavaScript wrapper → Hyperscript `call` bridge pattern. + +**Architecture:** +```javascript +// static/js/main.js - JavaScript event listeners (wrapper layer) +function initHoverSync() { + // PDF button hover sync + document.querySelectorAll('.pdf-btn, .menu-pdf-btn').forEach(btn => { + btn.addEventListener('mouseenter', () => syncPdfHover(true)); + btn.addEventListener('mouseleave', () => syncPdfHover(false)); + }); + + // Print button hover sync + document.querySelectorAll('.print-btn, .menu-print-btn').forEach(btn => { + btn.addEventListener('mouseenter', () => syncPrintHover(true)); + btn.addEventListener('mouseleave', () => syncPrintHover(false)); + }); + + // Zoom toggle hover + const zoomToggle = document.getElementById('zoom-toggle-btn'); + if (zoomToggle) { + zoomToggle.addEventListener('mouseenter', () => highlightZoomControl(true)); + zoomToggle.addEventListener('mouseleave', () => highlightZoomControl(false)); + } +} +``` + +```hyperscript +-- static/hyperscript/hover-sync._hs - Hyperscript logic layer +def syncPdfHover(show) + set pdfButtons to <.pdf-btn, .menu-pdf-btn/> + + if show is true + for btn in pdfButtons + add .pdf-hover-sync to btn + end + else + for btn in pdfButtons + remove .pdf-hover-sync from btn + end + end +end + +def syncPrintHover(show) + set printButtons to <.print-btn, .menu-print-btn/> + + if show is true + for btn in printButtons + add .print-hover-sync to btn + end + else + for btn in printButtons + remove .print-hover-sync from btn + end + end +end + +def highlightZoomControl(show) + set zoomWrapper to #zoom-wrapper + + if show is true + add .highlight to zoomWrapper + else + remove .highlight from zoomWrapper + end +end +``` + +```css +/* CSS provides the visual feedback */ +.pdf-btn.pdf-hover-sync, +.menu-pdf-btn.pdf-hover-sync { + background-color: rgba(255, 0, 0, 0.1); + transform: scale(1.05); +} + +.print-btn.print-hover-sync, +.menu-print-btn.print-hover-sync { + background-color: rgba(0, 0, 255, 0.1); + transform: scale(1.05); +} + +#zoom-wrapper.highlight { + outline: 2px solid var(--accent-blue); + outline-offset: 2px; +} +``` + +**How It Works:** +1. **User hovers over PDF button (action bar)** +2. **JavaScript `mouseenter` fires** → Calls `syncPdfHover(true)` +3. **Hyperscript function executes** → Selects ALL PDF buttons (`<.pdf-btn, .menu-pdf-btn/>`) +4. **Adds `.pdf-hover-sync` class** → Both action bar AND menu buttons get class +5. **CSS transition triggers** → Both buttons highlight simultaneously +6. **User moves mouse away** +7. **JavaScript `mouseleave` fires** → Calls `syncPdfHover(false)` +8. **Hyperscript removes class** → Highlight fades from both buttons + +**Benefits:** +- ✅ **Visual coherence** - Related UI elements respond together +- ✅ **No refresh needed** - Pure CSS transitions, no DOM manipulation +- ✅ **Maintainable** - Logic centralized in hyperscript functions +- ✅ **Reusable** - Pattern works for any synchronized hover states +- ✅ **Performance** - Class toggling is extremely fast +- ✅ **JavaScript-Hyperscript bridge** - Shows how to integrate both paradigms + +**Testing:** `tests/mjs/8-hover-sync.test.mjs` verifies all three hover sync patterns work without page refresh. + +**Key Innovation:** This pattern allows JavaScript DOM event listeners to trigger hyperscript logic, bridging the gap between imperative (JavaScript) and declarative (hyperscript) programming models. Essential for complex interactions like hover synchronization across separate UI components. + --- ### Hyperscript Organization Benefits: