## Implementation Plan: Add Loading/In-Progress Animations to Post Action Buttons

### Overview

Connect the three layers (CSS, templates, JS) that are currently missing for post action buttons.  
The existing `btn-spinner` + `is-loading` pattern is the intended design — we will extend it to the unmodified buttons.

### Step 1 – CSS

**File:** `devplacepy/static/css/base.css` (or the file containing `.btn.is-loading` and `.btn-spinner`)

Add selectors for all missing button classes so that `.is-loading` triggers `pointer-events: none` and shows the spinner child.

```css
/* Existing pattern: .btn.is-loading .btn-spinner ... */
/* Add these new rules: */

.post-action-btn.is-loading,
.comment-vote-btn.is-loading,
.comment-action-btn.is-loading,
.vote-star.is-loading,
.comment-form-submit.is-loading {
    pointer-events: none;
    opacity: 0.7;  /* optional: visual readonly cue */
}
```

(If the CSS for `.btn.is-loading` already sets `pointer-events: none; position: relative;` you may not need to repeat – just ensure the spinner is visible. Verify that `.btn-spinner` is positioned correctly inside these buttons; if not, add a generic rule `.is-loading > .btn-spinner { display: inline-block; }`.)

### Step 2 – Templates

Insert `<span class="btn-spinner" aria-hidden="true"></span>` before the text label in every button listed in the investigation report.  
The following templates need modification (paths relative to `devplacepy/templates/`):

| Template file | Button class / selector | Spinner insertion point |
|---------------|------------------------|--------------------------|
| `votes/_star_vote.html` | `.vote-star` | Inside `<button …>` before the star icon or text |
| `bookmarks/_bookmark_button.html` | `.post-action-btn.bookmark-btn` | Inside `<button …>` before bookmark text |
| `comments/_comment_form.html:12` | `.comment-form-submit` | Inside `<button …>` before “Submit” text |
| `comments/_comment_vote.html` (inferred) | `.comment-vote-btn` | Inside `<button …>` before vote arrow/text |
| `comments/_comment_actions.html` (inferred) | `.comment-action-btn` | Inside each action button (edit, delete, etc.) |
| `polls/_poll_vote.html` (inferred – PollManager) | `<form wrapped buttons>` | Inside the submit `<button>` |

Look at working examples (e.g. `issues.html:81`) to copy the exact markup pattern.  
**Important:** Do not remove existing classes – only add the `<span class="btn-spinner">` as the **first child** of the button element.

### Step 3 – JavaScript

#### 3a – OptimisticAction base class (used by VoteManager, BookmarkManager, ReactionBar, PollManager)

**File:** `devplacepy/static/js/OptimisticAction.js` (inferred path; locate the file containing `submit()` and `submitOptimistic()`)

Add a new private method `_setLoading(button, loading)` that toggles the button’s disabled state and `is-loading` class. Then call it inside both methods.

```javascript
_setLoading(button, loading) {
    if (!button) return;
    button.disabled = loading;
    if (loading) {
        button.classList.add('is-loading');
    } else {
        button.classList.remove('is-loading');
    }
}
```

Modify `submitOptimistic(button, ...)` – it already exists with a button parameter? The investigation says “neither method touches the button”. We’ll add `button` as a required parameter.  
If existing implementation does not pass a button, update callers to pass `this.button` or similar (see step 3b).  
Add a `finally` block to always remove loading state.

#### 3b – Consumers of OptimisticAction

**Files:** `VoteManager.js`, `BookmarkManager.js`, `ReactionBar.js`, `PollManager.js`

Inside their click handlers (or wherever they call `this.submitOptimistic()`), **pass the button element** as the first argument. Example:

```javascript
// Inside event listener:
const button = event.currentTarget;  // or event.target.closest('button')
this.submitOptimistic(button, /* other args... */);
```

If any manager does not have a reference to the button, add one in the constructor or on click.

#### 3c – CommentManager

**File:** `CommentManager.js`

In every location that sets `button.disabled = true` (lines 22-43, 119-137, 206-209), also add:

```javascript
button.classList.add('is-loading');
```

And add corresponding removal on success/error (or in the `finally` block of the async handler).

#### 3d – FormManager (global form disable)

**File:** `FormManager.js`

`initFormDisable` already sets `is-loading` class. Ensure the CSS for `.btn.is-loading` works for all button classes. Since we added CSS for the specific classes in Step 1, the existing `is-loading` addition will now work for those forms as well. Verify that no existing flow is broken (e.g. `data-live-form` skip still works).

### Step 4 – Execution Environment

The earlier failures were caused by pip refusing to install into the system Python environment. To mitigate, include the following in your execution script:

```bash
# Create and use a virtual environment to avoid PEP 668 restrictions
python3 -m venv /tmp/venv
source /tmp/venv/bin/activate
pip install -e '.[dev]' -q
pip install -q ruff
```

Then run the test and lint commands within the virtual environment.

---

## Definition of Done

1. **CSS** – All button classes listed in Step 1 have `.is-loading` rules that disable interaction and show the spinner child. A manual check of `base.css` confirms new selectors are present.

2. **Templates** – Every post action button template (star, bookmark, comment submit, comment vote, comment actions, poll submit) now contains a `<span class="btn-spinner" aria-hidden="true">` before its label. Verified by grepping each template for `btn-spinner`.

3. **JavaScript** –  
   - `OptimisticAction.js` has a `_setLoading()` method used in `submit()` and `submitOptimistic()`.  
   - All four consumer managers (Vote, Bookmark, ReactionBar, Poll) pass the button element to `submitOptimistic()`.  
   - `CommentManager.js` adds `is-loading` class at every place it sets `disabled = true`.

4. **No regressions** – The existing `data-live-form` escape hatch (MessagesLayout) remains untouched and still works. The global `FormManager.initFormDisable` continues to skip those forms.

5. **Project commands pass** –  
   - `pip install -e '.[dev]' -q && make test-unit` exits 0 (inside a virtual environment).  
   - `pip install -q ruff && ruff check .` exits 0 (inside a virtual environment).

6. **Visual verification** (optional but recommended) – In the running application, clicking a vote star, bookmark button, comment submit, etc. shows a spinning indicator and the button becomes disabled until the network request completes. On error, the loading state is removed.