# ADR 003: HTMX-Based Write Operations

## Status
Accepted

## Context
Phase 1-2 of the dashboard were read-only views. Phase 3 required transforming it into an active command center where users can:
- Complete tasks/cards
- Create new tasks
- Add shopping items
- Toggle item states

Traditional approaches would require either:
- Full page reloads (poor UX)
- Complex JavaScript SPA framework (React, Vue)
- Custom AJAX handlers

## Decision
Use **HTMX attributes** for all write operations, returning HTML partials that swap into the DOM.

### Technical Details:

**Pattern: Form submission with partial swap**
```html
<form hx-post="/complete-atom"
      hx-vals='{"id": "{{.ID}}", "source": "{{.Source}}"}'
      hx-target="closest .task-card"
      hx-swap="outerHTML">
    <button type="submit">✓</button>
</form>
```

**Handler returns HTML partial:**
```go
func (h *Handler) HandleCompleteAtom(w http.ResponseWriter, r *http.Request) {
    // ... complete the task via API
    // Return completed state HTML or empty response
    HTMLResponse(w, h.renderer, "completed-atom", data)
}
```

**Quick Add Pattern:**
```html
<input hx-post="/unified-add"
       hx-trigger="keyup[key=='Enter']"
       hx-target="#task-list"
       hx-swap="afterbegin"
       name="content">
```

**Optimistic UI:**
- Use CSS transitions for immediate visual feedback
- On error, swap in error banner partial
- HTMX `hx-on` events for state management

**Unified Quick Add:**
- Single input parses text for routing hints
- `#groceries` tag → routes to shopping
- `#work` tag → routes to Trello
- Default → routes to Todoist

## Consequences

**Pros:**
- No JavaScript framework needed
- Server renders all HTML (single source of truth)
- Progressive enhancement (works without JS, enhanced with)
- Trivial to test (just HTTP handlers)
- Fast development cycle

**Cons:**
- More HTTP requests than SPA approach
- Partial HTML responses require careful template organization
- Limited offline capability

## Alternatives Considered

**Option A: React/Vue SPA**
- Rejected: Overkill for this use case, adds build complexity, harder to maintain

**Option B: Full page reloads**
- Rejected: Poor UX, especially on mobile

**Option C: Custom JavaScript + JSON APIs**
- Rejected: Reinventing what HTMX provides, more code to maintain