puffpastry-frontend/.junie/plans/highlight-user-proposal-and-amendment-votes.md

---
sessionId: session-261005-184808-15gg
---

# Requirements

### Overview & Goals
Provide immediate, clear visual feedback to users regarding their previous voting decisions on any visited proposal and its associated amendments. By leveraging `ProposalService.getUserVotes`, the application eliminates cognitive friction, prevents redundant vote attempts, and enhances user confidence by highlighting previously selected voting choices across proposal and amendment action controls.

### Scope
- **In Scope**:
  - Fetching user vote records on proposal load using `ProposalService.getUserVotes(proposalId)`.
  - Handling authenticated and unauthenticated states gracefully without blocking proposal content.
  - Updating `ProposalVotingCard.vue` to highlight the user's previous proposal vote (`Approve`, `Reject`, or `Abstain`) with active colored styling and accessible state.
  - Updating `AmendmentCarousel.vue` to color the quick-action approval (`Confirm`) and disapproval (`Cancel`) icons according to the user's vote on each amendment.
  - Synchronizing vote indicators immediately upon casting a new proposal or amendment vote.
- **Out of Scope**:
  - Modifying backend OpenAPI endpoints or database schemas.
  - Adding vote retraction/deletion workflows beyond standard vote casting.

### User Stories
- **As a governance participant**, I want to see my existing votes highlighted when I visit a proposal so that I immediately know whether I have already participated and what position I took.
- **As a voter evaluating amendments**, I want the approval/disapproval icons on each amendment card to reflect my past votes so that I can quickly review my stance without opening each amendment individually.

### Functional Requirements
- **Data Retrieval**:
  - When navigating to a proposal, `ProposalDetail.vue` must call `ProposalService.getUserVotes(proposalId)` to fetch all proposal and amendment votes cast by the current user.
  - Unauthenticated requests (e.g. 401 responses) or users with no recorded votes must be handled gracefully without throwing errors or breaking page rendering.
- **Proposal Voting Card States**:
  - If the user voted `VoteChoice.YES` (`yes` / `Positive`), the "Approve" button and icon must display active emerald styling.
  - If the user voted `VoteChoice.NO` (`no` / `Negative`), the "Reject" button and icon must display active rose styling.
  - If the user voted `VoteChoice.ABSTAIN` (`abstain` / `Abstain`), the "Abstain" button and icon must display active amber styling.
  - If the user has not voted, all buttons retain their default neutral resting styling with hover accents.
- **Amendment Quick-Action States**:
  - For each proposed amendment, if the user voted in favor (`inFavor === true`), the `Confirm` button/icon is colored emerald.
  - If the user voted against (`inFavor === false`), the `Cancel` button/icon is colored rose.
  - If unvoted, both icons retain neutral slate styling (`text-slate-400`).
- **Reactive Synchronization**:
  - Casting a vote on either the proposal or an amendment must promptly re-fetch or optimistically update the vote state so the visual indicators reflect the change without requiring a page reload.

### Non-Functional Requirements
- **Accessibility**: Include `aria-pressed="true"` or descriptive `aria-label` / `title` attributes on active buttons to inform screen readers of the user's recorded stance.
- **Efficiency**: Fetch proposal and amendment votes in a single network request (`getUserVotes`) to avoid N+1 queries.

# Technical Design

### Current Implementation
- `ProposalService.getUserVotes(proposalId: number): CancelablePromise<UserProposalVotes>` is available in `src/generated/typescript/services/ProposalService.ts` and returns:
  - `proposalVote?: ProposalVote | null` containing `choice: VoteChoice` (`'yes' | 'no' | 'abstain'`).
  - `amendmentVotes: Array<UserAmendmentVote>` containing `amendmentId: number` and `vote?: AmendmentVote | null` with `inFavor: boolean`.
- `src/views/ProposalView.vue` loads `proposal` and passes it to `src/components/ProposalDetail.vue`.
- `ProposalDetail.vue` renders:
  - `<ProposalVotingCard :proposal-id="proposal.id" @vote="recordVote" />`
  - `<AmendmentCarousel :proposal-id="proposal.id" />`
- Currently, neither component fetches `getUserVotes` or accepts user vote props; buttons in `ProposalVotingCard.vue` and `AmendmentCarousel.vue` display static unselected styling regardless of user voting history.

### Key Decisions
1. **Centralized Vote State in `ProposalDetail.vue`**:
   - *Decision*: Fetch `getUserVotes` in `ProposalDetail.vue` and pass relevant slice data as props down to `ProposalVotingCard.vue` and `AmendmentCarousel.vue`.
   - *Rationale*: Prevents duplicate API requests while ensuring both components remain pure presentational/reactive consumers synchronized to the single source of truth.
2. **Resilient Unauthenticated Handling**:
   - *Decision*: Wrap `ProposalService.getUserVotes` in a try/catch block; if 401 or network error occurs, silently default `userVotes` to `null`.
   - *Rationale*: Allows guest users or users without wallet connection to browse proposals seamlessly without console spam or UI disruption.
3. **Semantic Tailwind Color Tokens**:
   - *Decision*: Use Tailwind `emerald` (positive/approve), `rose` (negative/reject), and `amber` (abstain) classes with subtle background and border tints for active states.
   - *Rationale*: Matches existing design tokens across `Chip.vue`, `AmendmentCarousel.vue`, and `VotingControls.vue` while delivering high-contrast clarity.

### Proposed Changes

#### 1. `src/components/ProposalDetail.vue`
- Import `UserProposalVotes`, `UserAmendmentVote`, `VoteChoice` from generated typescript models.
- Add reactive state `const userVotes = ref<UserProposalVotes | null>(null);`.
- Implement `fetchUserVotes(proposalId: number)`:
  - Invoke `ProposalService.getUserVotes(proposalId)`.
  - Store response in `userVotes.value`.
  - On error (401/404/network), reset `userVotes.value = null`.
- Call `fetchUserVotes` in `onMounted` and within the `watch(() => props.proposal?.id)` handler.
- Pass `current-vote="userVotes?.proposalVote?.choice"` to `<ProposalVotingCard>`.
- Pass `:amendment-votes="userVotes?.amendmentVotes"` to `<AmendmentCarousel>`.
- Update `recordVote` to await `voteProposal` and immediately call `fetchUserVotes(props.proposal.id)`.

#### 2. `src/components/ProposalVotingCard.vue`
- Accept prop `currentVote?: VoteChoice | 'yes' | 'no' | 'abstain' | null`.
- Compute active helper booleans:
  - `isApproved = computed(() => props.currentVote === VoteChoice.YES || props.currentVote === 'yes')`
  - `isRejected = computed(() => props.currentVote === VoteChoice.NO || props.currentVote === 'no')`
  - `isAbstained = computed(() => props.currentVote === VoteChoice.ABSTAIN || props.currentVote === 'abstain')`
- Apply conditional classes:
  - Approve button: `:class="isApproved ? 'border-emerald-600 bg-emerald-50 text-emerald-700 ring-1 ring-emerald-500' : 'border-slate-300 bg-white text-slate-700 hover:border-green-600 hover:bg-green-600 hover:text-white'"`
  - Reject button: `:class="isRejected ? 'border-rose-600 bg-rose-50 text-rose-700 ring-1 ring-rose-500' : 'border-slate-300 bg-white text-slate-700 hover:border-red-600 hover:bg-red-600 hover:text-white'"`
  - Abstain button: `:class="isAbstained ? 'border-amber-500 bg-amber-50 text-amber-700 ring-1 ring-amber-500' : 'border-slate-300 bg-white text-slate-700 hover:border-amber-500 hover:bg-amber-500 hover:text-slate-950'"`
- Pass `aria-pressed` based on active vote status.

#### 3. `src/components/AmendmentCarousel.vue`
- Add prop `amendmentVotes?: UserAmendmentVote[]`.
- Create a computed lookup map or helper function `getAmendmentVote(amendmentId: number): boolean | null | undefined`:
  - Returns `true` if `vote?.inFavor === true`, `false` if `vote?.inFavor === false`, or `null`/`undefined` if unvoted.
- In the template for proposed amendments:
  - Highlight Confirm button with `text-emerald-600 bg-emerald-50 ring-1 ring-emerald-400` when `getAmendmentVote(amendment.id) === true`.
  - Highlight Cancel button with `text-rose-600 bg-rose-50 ring-1 ring-rose-400` when `getAmendmentVote(amendment.id) === false`.
- Emit a `voted` event when `confirm` or `reject` completes so parent `ProposalDetail` can refresh `getUserVotes`.

### Architecture Diagram

```mermaid
graph TD
    PV[ProposalView.vue] --> PD[ProposalDetail.vue]
    PD -->|1. getUserVotes proposalId| PS[ProposalService API]
    PS -->|UserProposalVotes| PD
    PD -->|currentVote| PVC[ProposalVotingCard.vue]
    PD -->|amendmentVotes| AC[AmendmentCarousel.vue]
    PVC -->|@vote -> voteProposal + refresh| PD
    AC -->|@voted -> voteAmendment + refresh| PD
```

### File Structure
- `src/components/ProposalDetail.vue` *(Modified)*: Adds user votes fetching, state management, and props dispatch.
- `src/components/ProposalVotingCard.vue` *(Modified)*: Receives active proposal vote prop and renders highlight styles for Approve, Reject, and Abstain.
- `src/components/AmendmentCarousel.vue` *(Modified)*: Receives amendment votes prop, applies active color styles on Confirm/Cancel icons, and notifies parent on vote.

### Risks & Mitigations
- **Unauthenticated / Expired Tokens**: `getUserVotes` will return 401 when tokens are missing or invalid. *Mitigation*: Catch 401 errors gracefully and treat user votes as empty without throwing alerts.
- **Race Condition on Voting**: Multiple quick clicks on vote actions. *Mitigation*: Await API resolution and update state reactivity to ensure visual indicators match persisted server state.

# Testing

### Validation Approach
Verify the functionality by loading proposals in authenticated and unauthenticated states, testing all vote positions on both proposal and amendment components, and confirming real-time UI updates upon casting votes.

### Key Scenarios
1. **Proposal Vote Highlighting**:
   - Navigate to a proposal where the user previously voted "Approve" -> Verify the Approve button in `ProposalVotingCard` is highlighted in emerald with active border/background.
   - Navigate to a proposal where the user previously voted "Reject" -> Verify the Reject button is highlighted in rose.
   - Navigate to a proposal where the user previously voted "Abstain" -> Verify the Abstain button is highlighted in amber.
   - Navigate to an unvoted proposal -> Verify all 3 buttons are rendered in their neutral resting state.
2. **Amendment Vote Highlighting**:
   - For an amendment where the user voted in favor (`inFavor: true`) -> Verify the checkmark (`Confirm`) icon is highlighted in emerald.
   - For an amendment where the user voted against (`inFavor: false`) -> Verify the cross (`Cancel`) icon is highlighted in rose.
   - For unvoted amendments -> Verify both icons render in neutral slate color (`text-slate-400`).
3. **Dynamic Voting State Updates**:
   - Click "Approve" on an unvoted proposal -> Verify the Approve button immediately shifts to active highlighted state upon API confirmation.
   - Click "Confirm" on a proposed amendment -> Verify the checkmark icon immediately transitions to the active emerald state.
4. **Guest / Unauthenticated Experience**:
   - View proposals with no token in `localStorage` -> Verify the proposal details, comments, and amendment carousel render properly with default unselected action buttons and no console runtime errors.

### Edge Cases
- **No Amendments on Proposal**: Verify `amendmentVotes` handles empty arrays safely without runtime errors.
- **Token Expiry**: When token expires mid-session, API failures are caught cleanly, leaving icons in fallback neutral states.

# Delivery Steps

### ✓ Step 1: Integrate user vote retrieval and state management in ProposalDetail
ProposalDetail fetches and manages user vote records for the active proposal and its amendments, maintaining synchronized reactive state.

- Implement `fetchUserVotes` in `src/components/ProposalDetail.vue` using `ProposalService.getUserVotes(props.proposal.id)`.
- Gracefully handle unauthorized (401), not found (404), or network error states when a user is unauthenticated or has no recorded votes.
- Add reactive state `userVotes` typed as `UserProposalVotes | null` to track active proposal and amendment votes.
- Trigger `fetchUserVotes` on component mount and watch `proposal.id` changes to keep user vote state updated when navigating proposals.
- Pass the proposal vote selection (`userVotes?.proposalVote?.choice`) to `ProposalVotingCard` and the amendment vote mapping to `AmendmentCarousel`.

### ✓ Step 2: Render active vote indicators in ProposalVotingCard
ProposalVotingCard visually indicates the user's previously cast vote with distinct color and container styling for Approve, Reject, and Abstain options.

- Add a `currentVote` prop to `src/components/ProposalVotingCard.vue` accepting `VoteChoice | 'Positive' | 'Negative' | 'Abstain' | null | undefined`.
- Update button styles to reflect active selection states:
  - **Approve**: Highlight with emerald border/background (`border-emerald-500 bg-emerald-50 text-emerald-700`) and emerald `Confirm` icon.
  - **Reject**: Highlight with rose border/background (`border-rose-500 bg-rose-50 text-rose-700`) and rose `Cancel` icon.
  - **Abstain**: Highlight with amber border/background (`border-amber-500 bg-amber-50 text-amber-700`) and amber `Abstain` icon.
- Add `aria-pressed` attributes to buttons for assistive technology feedback.
- Update `recordVote` in `ProposalDetail.vue` to refresh or optimistically update user vote state immediately after casting a vote.

### ✓ Step 3: Highlight previous votes in AmendmentCarousel and synchronize state
AmendmentCarousel displays colored approval and disapproval quick-action icons corresponding to the user's recorded amendment votes.

- Update `src/components/AmendmentCarousel.vue` to accept amendment vote data (e.g. `userVotes?: UserAmendmentVote[]` or a vote lookup map) from `ProposalDetail.vue`.
- Derive helper methods/computed maps to resolve a user's vote (`inFavor: true`, `inFavor: false`, or unvoted) for each amendment ID.
- Update the quick-action button styles in proposed amendment cards:
  - **Approve (in favor)**: Render active emerald styling (`text-emerald-600 bg-emerald-50 border border-emerald-200`) on the `Confirm` icon button.
  - **Reject (against)**: Render active rose styling (`text-rose-600 bg-rose-50 border border-rose-200`) on the `Cancel` icon button.
  - **Unvoted**: Maintain neutral resting styling (`text-slate-400 hover:text-emerald-500` / `hover:text-rose-500`).
- Update `confirm` and `reject` voting handlers in `AmendmentCarousel.vue` to emit vote events or trigger vote refreshes to ensure immediate UI synchronization.