# Implement HTMX Loading Indicators Throughout CV Application

<objective>
Systematically identify and implement HTMX loading indicators across all interactive elements in the CV application. The goal is to provide visual feedback during HTMX requests, improving perceived performance and user experience by showing users that their actions are being processed.

**What are HTMX Indicators?**
HTMX provides a built-in `htmx-indicator` class that automatically shows/hides elements during HTMX requests. When an HTMX request is in progress, elements with this class become visible; when the request completes, they hide automatically.

This will make the application feel more responsive and professional by giving users immediate visual feedback for all interactive actions.
</objective>

<context>
**Current State:**
- The CV application uses HTMX extensively for dynamic interactions:
  - Language switching (EN/ES)
  - Toggle controls (length, logos, theme)
  - Hamburger menu interactions
  - Other dynamic content updates
- Currently, there's **no visual feedback** during these requests - users click and wait with no indication that something is happening

**HTMX Indicator Pattern:**
```html
<button hx-get="/endpoint">
    Click Me!
    <img class="htmx-indicator" src="/spinner.gif" alt="Loading...">
</button>
```

**How it works:**
1. By default, elements with `htmx-indicator` class are hidden (`opacity: 0`)
2. When parent element initiates an HTMX request, HTMX automatically adds `htmx-request` class
3. CSS rule `.htmx-request .htmx-indicator` shows the indicator (`opacity: 1`)
4. When request completes, `htmx-request` class is removed, hiding the indicator

**Benefits:**
- Zero JavaScript required - pure declarative HTML
- Automatic show/hide behavior
- Works with any visual element (spinners, text, icons, etc.)
- Improves perceived performance
- Professional UX standard

**Files with HTMX Interactions:**
@templates/partials/navigation/language-selector.html - Language switching buttons
@templates/partials/navigation/view-controls.html - Toggle controls (length, logos, theme)
@templates/partials/navigation/hamburger-menu.html - Menu interactions
@templates/language-switch.html - Language switch response template
</context>

<requirements>
1. **Comprehensive Audit:**
   - Search entire codebase for HTMX attributes: `hx-get`, `hx-post`, `hx-put`, `hx-delete`, `hx-patch`
   - Identify every interactive element that triggers HTMX requests
   - Categorize by interaction type (buttons, toggles, forms, links, etc.)

2. **Appropriate Indicator Selection:**
   - **Language buttons:** Show loading spinner or "Switching..." text
   - **Toggle switches:** Show subtle spinner next to toggle
   - **Forms/inputs:** Show spinner or loading state
   - **Menu interactions:** Show loading indicator if applicable
   - Consider using iconify-icon for spinners (already in use): `<iconify-icon icon="mdi:loading" class="htmx-indicator spinning"></iconify-icon>`

3. **Visual Design:**
   - Indicators should be subtle and non-intrusive
   - Match existing design language and color palette
   - Use consistent styling across all indicators
   - Consider size and positioning relative to parent element
   - Ensure indicators don't cause layout shift when appearing

4. **CSS Implementation:**
   - Use HTMX's default indicator pattern:
     ```css
     .htmx-indicator {
       opacity: 0;
       transition: opacity 200ms ease;
     }
     .htmx-request .htmx-indicator,
     .htmx-request.htmx-indicator {
       opacity: 1;
     }
     ```
   - Add spinning animation for spinner icons:
     ```css
     .htmx-indicator.spinning {
       animation: spin 1s linear infinite;
     }
     @keyframes spin {
       from { transform: rotate(0deg); }
       to { transform: rotate(360deg); }
     }
     ```

5. **Custom Indicators (Optional):**
   - For specific cases, use `hx-indicator="#custom-id"` to target a different element
   - Example: Show a global loading bar at top of page for major operations
   - Document when and why custom indicators are used vs default pattern

6. **Performance Considerations:**
   - Indicators should use GPU-accelerated properties (opacity, transform)
   - Avoid layout shifts when indicators appear/disappear
   - Keep animations lightweight and smooth (60fps)

7. **Edge Cases:**
   - Very fast responses (<100ms): Indicator might flash briefly - acceptable or add minimum display time?
   - Slow responses (>2s): Ensure indicator remains visible entire duration
   - Failed requests: Indicator should hide properly on error states
   - Rapid clicking: Multiple indicators shouldn't stack or break

8. **Accessibility:**
   - Include `aria-busy="true"` during loading states if needed
   - Ensure screen readers can perceive loading states
   - Respect `prefers-reduced-motion` for spinning animations
</requirements>

<implementation>
**Step-by-Step Implementation Plan:**

**Phase 1: Audit Current HTMX Usage**
1. Search all template files for `hx-get`, `hx-post`, etc.
2. Create a list/table of all HTMX interactions found:
   - Element type (button, toggle, link)
   - HTMX attribute used
   - Current file location
   - Proposed indicator type

**Phase 2: Design Indicator Components**
1. Choose indicator visuals:
   - Spinner icon (iconify: `mdi:loading` or `mdi:dots-horizontal`)
   - Text indicators ("Loading...", "Switching...", etc.)
   - Progress bars (if applicable)

2. Create reusable indicator patterns:
   - Standard button spinner
   - Toggle switch spinner
   - Inline text spinner

**Phase 3: Implement CSS Styles**
Add to `static/css/main.css`:
```css
/* ============================================================================
   HTMX Loading Indicators
   ========================================================================= */

/* Base indicator styles - hidden by default */
.htmx-indicator {
  opacity: 0;
  transition: opacity 200ms ease-in-out;
  pointer-events: none;
}

/* Show indicators during HTMX requests */
.htmx-request .htmx-indicator,
.htmx-request.htmx-indicator {
  opacity: 1;
}

/* Spinning animation for loading icons */
.htmx-indicator.spinning {
  display: inline-block;
  animation: htmx-spin 1s linear infinite;
}

@keyframes htmx-spin {
  from { transform: rotate(0deg); }
  to { transform: rotate(360deg); }
}

/* Respect reduced motion preference */
@media (prefers-reduced-motion: reduce) {
  .htmx-indicator.spinning {
    animation: none;
  }
  .htmx-indicator {
    transition: none;
  }
}

/* Specific indicator variants */
.htmx-indicator.inline {
  display: inline-block;
  margin-left: 8px;
  vertical-align: middle;
}

.htmx-indicator.small {
  width: 16px;
  height: 16px;
}

.htmx-indicator.medium {
  width: 20px;
  height: 20px;
}
```

**Phase 4: Update Templates**

**Example 1: Language Selector Buttons**
```html
<button class="selector-btn {{if eq .Lang "en"}}active{{end}}"
        hx-get="/switch-language?lang=en"
        hx-target="#language-selector"
        hx-swap="outerHTML">
    <span>English</span>
    <iconify-icon icon="mdi:loading"
                  class="htmx-indicator spinning small inline"
                  width="14"
                  height="14"></iconify-icon>
</button>
```

**Example 2: Toggle Controls**
```html
<input type="checkbox"
       id="lengthToggle"
       hx-post="/toggle/length?lang={{.Lang}}"
       hx-swap="none">
<iconify-icon icon="mdi:loading"
              class="htmx-indicator spinning small"
              width="14"
              height="14"></iconify-icon>
```

**Example 3: Custom Indicator for Global Actions**
```html
<!-- At top of page -->
<div id="global-loading-bar" class="htmx-indicator global-loading">
  <div class="loading-bar-fill"></div>
</div>

<!-- In button -->
<button hx-get="/heavy-operation"
        hx-indicator="#global-loading-bar">
    Run Heavy Operation
</button>
```

**Phase 5: Test All Indicators**
1. Visually verify each indicator appears during requests
2. Test with throttled network (simulate slow responses)
3. Test rapid clicking (ensure no broken states)
4. Test accessibility (screen readers, reduced motion)

**What to Prioritize:**
1. High-frequency interactions first (language switching, toggles)
2. User-initiated actions that might take >200ms
3. Actions where users expect feedback (form submissions, data changes)
4. Skip indicators for instant operations (<50ms response time)

**What to Avoid:**
- Don't add indicators to every single element blindly - use judgment
- Don't use heavy animations or large images - keep it lightweight
- Don't cause layout shifts when indicators appear
- Don't forget to test with slow network conditions
- Don't over-engineer - simple spinners are often best
</implementation>

<output>
The following files will be modified:

1. **`./static/css/main.css`**
   - Add HTMX indicator base styles
   - Add spinning animation keyframes
   - Add indicator size variants (small, medium, large)
   - Add reduced-motion overrides

2. **`./templates/partials/navigation/language-selector.html`**
   - Add loading indicators to EN/ES buttons
   - Use iconify spinner icon with `htmx-indicator` class

3. **`./templates/partials/navigation/view-controls.html`**
   - Add loading indicators to toggle controls (length, logos, theme)
   - Position indicators appropriately next to toggles

4. **`./templates/partials/navigation/hamburger-menu.html`**
   - Add indicators if menu has HTMX interactions requiring feedback

5. **Any other template files with HTMX interactions** (discovered during audit)
   - Add appropriate indicators based on interaction type

**Optional (if needed):**
6. **`./templates/partials/global-loading-indicator.html`** (NEW)
   - Create reusable global loading indicator component
   - For major operations affecting entire page

**Documentation:**
7. **Add comments in code** explaining indicator patterns for future maintenance
</output>

<verification>
Before declaring complete, perform these comprehensive tests:

**1. Visual Verification:**
- [ ] Language switch: Spinner appears on clicked button during switch
- [ ] Length toggle: Indicator appears during toggle state change
- [ ] Logo toggle: Indicator appears during toggle state change
- [ ] Theme toggle: Indicator appears during toggle state change
- [ ] All indicators disappear when requests complete
- [ ] Indicators are visually consistent across all elements

**2. Timing Tests:**
- [ ] Fast response (<100ms): Indicator appears briefly (acceptable flash)
- [ ] Normal response (200-500ms): Indicator clearly visible
- [ ] Slow response (>1s): Indicator remains visible entire duration
- [ ] Indicators hide immediately when response arrives

**3. Network Throttling:**
- [ ] Open DevTools → Network → Throttle to "Slow 3G"
- [ ] Test all HTMX interactions with slow network
- [ ] Verify indicators remain visible during extended load times
- [ ] Verify no console errors or broken states

**4. Rapid Interaction Testing:**
- [ ] Rapidly click language buttons multiple times
- [ ] Rapidly toggle switches back and forth
- [ ] Verify indicators don't stack or cause visual glitches
- [ ] Verify final state is correct after rapid clicking

**5. Accessibility Testing:**
- [ ] Enable "Reduce motion" in OS settings
- [ ] Verify spinning animations are disabled
- [ ] Verify indicators still appear (just without animation)
- [ ] Test with screen reader - loading states are announced

**6. Layout Stability:**
- [ ] Indicators don't cause content to shift when appearing
- [ ] No cumulative layout shift (CLS) issues
- [ ] Buttons/toggles maintain consistent size
- [ ] Indicators positioned properly in all viewport sizes

**7. Browser Compatibility:**
- [ ] Chrome: All indicators work smoothly
- [ ] Firefox: All indicators work smoothly
- [ ] Safari: All indicators work smoothly
- [ ] Mobile browsers: Touch interactions show indicators

**8. Error Handling:**
- [ ] Simulate failed request (disable backend or use invalid endpoint)
- [ ] Verify indicator hides on error
- [ ] Verify error state is handled gracefully

**Success Indicators:**
✅ All HTMX interactions have appropriate loading indicators
✅ Indicators appear immediately when action is triggered
✅ Indicators hide immediately when request completes
✅ Animations are smooth and performant (60fps)
✅ No layout shifts when indicators appear/disappear
✅ Accessibility requirements met (reduced motion, screen readers)
✅ Consistent visual design across all indicators
✅ Code is maintainable and well-documented
</verification>

<success_criteria>
1. Every HTMX interaction has an appropriate loading indicator
2. Indicators use the standard `htmx-indicator` class pattern
3. Visual feedback appears within 50ms of user action
4. Indicators are subtle and don't distract from content
5. Spinning animations are smooth and GPU-accelerated
6. Respects `prefers-reduced-motion` accessibility setting
7. No layout shifts or visual glitches when indicators show/hide
8. Works consistently across modern browsers and device sizes
9. Code follows existing project patterns and conventions
10. Implementation is maintainable with clear documentation
</success_criteria>

<research>
**Files to Examine:**
- All template files in `templates/` and `templates/partials/`
- Search for HTMX attributes: `hx-get`, `hx-post`, `hx-put`, `hx-delete`, `hx-patch`
- Review existing CSS for any indicator patterns already in use
- Check if iconify-icon is already used for other icons (reuse pattern)

**Questions to Answer:**
1. What HTMX interactions exist in the codebase?
2. Which interactions would benefit most from loading indicators?
3. Are there any existing indicator patterns to build upon?
4. What icon library is already in use (iconify detected)?
5. What are the current transition/animation timings used in the project?
</research>

<references>
**HTMX Documentation:**
- Request indicators: https://htmx.org/attributes/hx-indicator/
- CSS transitions: https://htmx.org/examples/animations/
- Request lifecycle events: https://htmx.org/events/

**Best Practices:**
- Use subtle, non-intrusive indicators
- Match existing design patterns
- Prioritize high-frequency user actions
- Test with throttled network to verify visibility
- Always respect accessibility preferences

**Pattern Reference:**
```html
<!-- Default pattern (indicator inside triggering element) -->
<button hx-get="/endpoint">
    Action
    <span class="htmx-indicator">Loading...</span>
</button>

<!-- Custom indicator (target different element) -->
<button hx-get="/endpoint" hx-indicator="#my-indicator">
    Action
</button>
<div id="my-indicator" class="htmx-indicator">Loading...</div>
```
</references>

<additional_notes>
**Implementation Philosophy:**
- Start with the most frequently used interactions
- Keep indicators simple and consistent
- Prefer iconify-icon spinners (already in use in project)
- Don't over-engineer - simple is better
- Test with real network conditions (throttling)
- Document patterns for future developers

**Quick Win Opportunities:**
1. Language selector buttons - high visibility, user-initiated
2. Toggle controls - frequent user interactions
3. Any form submissions or data mutations

**Future Enhancements:**
- Consider global loading bar for major page transitions
- Add progress indicators for multi-step operations
- Implement skeleton loaders for content-heavy responses (separate from this task)
</additional_notes>