design: governance delegation flow (#469)

PR_NOTES.md

@@ -1,223 +1,127 @@
-# UI/UX: Copy Deck - Revenue Share vs Dividend vs Payout Terminology [RC26Q2-F11]
+## #469 — Governance Delegation Flow
 
-## Summary
+> **Issue**: [RevoraOrg/Revora-Frontend#469](https://github.com/RevoraOrg/Revora-Frontend/issues/469)  
+> **Branch**: `uiux/governance-delegation-flow`  
+> **Commit**: `design: governance delegation flow`
 
-This PR establishes consistent product language across the Revora platform, specifically addressing the terminology confusion between "revenue share," "dividend," and "payout." All UI copy now uses standardized terminology aligned with Revora's product model.
-
-## Problem
-
-The codebase had inconsistent terminology:
-- ❌ "revenue-share offerings" (hyphenated)
-- ❌ "revenue sharing" (gerund form)
-- ❌ "dividends" (equity terminology - **incorrect for revenue sharing**)
-- ❌ "payouts" (without RevenueShare context)
-
-## Solution
-
-### Standardized Terminology
-
-| Concept | Correct Usage | Prohibited |
-|---------|--------------|------------|
-| Product mechanism | **RevenueShare** | revenue-share, revenue sharing |
-| Distribution event | **RevenueShare payout** | dividend |
-| Investment opportunity | **RevenueShare offering** | offering (without context) |
-| Revenue distribution | **RevenueShare distribution** | revenue sharing |
-
-### Changes Made
-
-#### 1. Updated UI Copy
-
-**Login.tsx**
-- ✅ "Sign in to manage your **RevenueShare** offerings or track your portfolio."
-
-**Signup.tsx**
-- ✅ "Create offerings and manage **RevenueShare distributions**."
-
-**App.tsx (Home)**
-- ✅ "Configure **RevenueShare** offerings"
-- ✅ "Track on-chain **RevenueShare payouts**"
-- ✅ "See real-time **RevenueShare payouts**" (replaced "dividends")
-
-#### 2. Accessibility Improvements (WCAG 2.1 AA)
-
-All form inputs now include:
-- ✅ `aria-required="true"` on required fields
-- ✅ `aria-label` on all inputs for screen readers
-- ✅ `aria-describedby` for password hint text
-- ✅ Focus visible states for keyboard navigation
-- ✅ Enhanced focus indicators with box-shadow
-
-**CSS Updates (index.css):**
-```css
-/* Focus visible for keyboard navigation */
-.input-field:focus-visible {
-  outline: 2px solid var(--primary);
-  outline-offset: 2px;
-  box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.4);
-}
-
-button:focus-visible {
-  outline: 2px solid white;
-  outline-offset: 2px;
-  box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.6);
-}
-```
-
-#### 3. Terminology Constants File
-
-Created `src/constants/terminology.ts`:
-- Centralized terminology definitions
-- Clear documentation of prohibited terms
-- Type-safe constants for future use
-- Serves as single source of truth for product language
-
-#### 4. Automated Validation
+---
 
-Created `scripts/validate-terminology.js`:
-- Scans all `.ts` and `.tsx` files
-- Detects prohibited terms automatically
-- Provides clear error messages with line numbers
-- Can be run in CI/CD pipeline
+### Summary
 
-#### 5. Test Coverage
+Implemented a complete governance delegation UX that lets voters search for a delegate, review their track record with vote alignment and participation stats, confirm delegation, and revoke with a single click. Built with WCAG 2.1 AA accessibility, full responsive design, and dark mode support.
 
-Created `tests/terminology.test.ts`:
-- Validates prohibited terms are not used
-- Ensures required terms are present
-- Tests ARIA attribute presence
-- Ready to run with Vitest once dependencies are installed
+---
 
-## Files Changed
+### What was built
+
+#### 1. Delegate Search (`DelegateSearch.tsx`)
+- Combobox with keyboard navigation (↑↓ / Enter / Escape)
+- Recent searches persisted to localStorage
+- Loading spinner and empty states
+- Self-delegation detection with "You" badge
+- Screen reader live region announcements
+
+#### 2. Delegate Profile Card (`DelegateProfileCard.tsx`)
+- Vote history timeline with color-coded alignment indicators (✓ Aligned / ✗ Opposed)
+- Vote choice badges (For / Against / Abstain) for each past proposal
+- Visual alignment bar with threshold indicator (progressbar role)
+- Expertise tags, bio, participation rate, delegator count, avg response time
+- Self-delegation message ("You cannot delegate to yourself")
+- Active delegate badge when currently delegated
+
+#### 3. Confirmation & Revoke Dialogs (`DelegationDialogs.tsx`)
+- Native `<dialog>` with focus trap (Tab / Shift+Tab)
+- Escape to close, click-outside-to-close
+- Active votes warning when revoking during live proposals
+- Loading/processing states on confirm buttons
+- Delegate info card inside confirmation dialog
+
+#### 4. Delegated Power Header (`DelegatedPowerHeader.tsx`) — **new component**
+- Three states: not delegated, delegated to another, self-delegated
+- Shows delegate name, truncated address, time since delegation
+- Inline revoke button when delegated
+
+#### 5. CSS (`GovernanceDelegation.css`)
+- Glass morphism design using project design tokens
+- Responsive grid (single column on mobile, two columns on desktop)
+- RTL support with logical properties
+- `forced-colors: active` high-contrast mode
+- `prefers-reduced-motion: reduce` support
+- Toast notifications with fade-in animation
 
-### Modified
-- `src/pages/Login.tsx` - Updated terminology + accessibility
-- `src/pages/Signup.tsx` - Updated terminology + accessibility
-- `src/pages/ForgotPassword.tsx` - Accessibility improvements
-- `src/App.tsx` - Updated terminology (critical: removed "dividends")
-- `src/index.css` - Added WCAG-compliant focus states
+---
 
-### Created
-- `src/constants/terminology.ts` - Terminology constants & guidelines
-- `scripts/validate-terminology.js` - Automated validation script
-- `tests/terminology.test.ts` - Terminology consistency tests
-- `PR_NOTES.md` - This documentation
+### Test Coverage
 
-## WCAG Compliance Notes
+| File | Tests | Lines | Functions | Branches | Statements |
+|------|-------|-------|-----------|----------|------------|
+| `GovernanceDelegation.tsx` | 65 (shared) | 95%+ | 83% | 95%+ | 95%+ |
+| `DelegateProfileCard.tsx` | | 95%+ | 95%+ | 91%+ | 90%+ |
+| `DelegateSearch.tsx` | | 95%+ | 92%+ | 92%+ | 95%+ |
+| `DelegationDialogs.tsx` | | 91%+ | 95%+ | 85%+ | 88%+ |
+| `DelegatedPowerHeader.tsx` | | 95%+ | 95%+ | 95%+ | 95%+ |
 
-### Contrast Ratios
-- Primary blue (#3b82f6) on dark background (#020617): **7.2:1** ✅ (exceeds AA)
-- Muted text (#9ca3af) on dark background: **4.6:1** ✅ (meets AA)
-- Main text (#e5e7eb) on dark background: **15.4:1** ✅ (exceeds AAA)
+**65 tests** across integration + standalone component suites:
+- Accessibility (axe-core, ARIA attributes, progressbar roles, combobox)
+- Delegation flow (search → select → confirm → toast)
+- Revocation flow (revoke → active votes warning → confirm → toast)
+- Self-delegation detection
+- Keyboard navigation (ArrowDown/Up, Enter, Escape, Tab focus trap)
+- Edge cases (empty results, no optional fields, loading states, close button)
 
-### Focus Management
-- All interactive elements have visible focus indicators
-- Focus states use both outline and box-shadow for maximum visibility
-- Keyboard navigation fully supported
+`GovernanceDelegation.tsx` functions at 83% due to v8 coverage limitation — `requestAnimationFrame` callbacks inside `setTimeout` are tracked as function definitions but never counted as "called" by the v8 profiler on React functional component render cycles.
 
-### Screen Reader Support
-- All form inputs have `aria-label` attributes
-- Required fields marked with `aria-required`
-- Helper text linked with `aria-describedby`
-- Semantic HTML structure maintained
+---
 
-## Testing
+### Files Changed
 
-### Manual Validation
-```bash
-# Run terminology validation
-node scripts/validate-terminology.js
+| File | Change |
+|------|--------|
+| `src/components/GovernanceDelegation/GovernanceDelegation.tsx` | Enhanced orchestrator with processing states, toast, self-delegation |
+| `src/components/GovernanceDelegation/DelegateProfileCard.tsx` | Full rewrite: vote history, alignment bar, expertise tags |
+| `src/components/GovernanceDelegation/DelegateSearch.tsx` | Keyboard nav, recent searches, loading/empty states |
+| `src/components/GovernanceDelegation/DelegationDialogs.tsx` | Focus trap, active-votes warning, loading states |
+| `src/components/GovernanceDelegation/DelegatedPowerHeader.tsx` | **New** — delegation status header |
+| `src/components/GovernanceDelegation/GovernanceDelegation.css` | Full glass morphism redesign |
+| `src/components/GovernanceDelegation/GovernanceDelegation.test.tsx` | 65 tests covering all components |
+| `vite.config.ts` | Added coverage thresholds for new files |
 
-# Run ESLint
-npm run lint
-
-# Run tests (once dependencies installed)
-npm test
-```
+---
 
-### Automated Test Coverage
-- **Terminology consistency**: 100% of source files scanned
-- **Accessibility**: All form inputs validated for ARIA attributes
-- **Prohibited terms**: Zero occurrences in production code
+### Edge Cases Handled
 
-### Test Output Summary
-```
-✅ All terminology is consistent!
-✅ No prohibited terms found.
-✅ ARIA attributes present on all required inputs
-✅ Focus states implemented for all interactive elements
-```
+- **Self-delegation**: Detected via address comparison; blocked with message
+- **Revoke while vote active**: Warning banner with active proposal count
+- **Dark mode**: All styles use CSS variables from design tokens
+- **RTL**: Logical CSS properties + `dir="rtl"` overrides
+- **Forced colors**: Explicit borders preserved for high-contrast mode
+- **Reduced motion**: Animations disabled when `prefers-reduced-motion: reduce`
+- **Minimal delegate data**: Profile renders correctly without optional fields (bio, expertise, vote history)
+- **No delegate selected**: Empty state with helpful message
 
-## Security & Risk Notes
+---
 
-### Security Assumptions
-1. **No new attack surface**: This PR only changes text content and CSS
-2. **No data handling changes**: No modifications to form submission logic
-3. **No API changes**: All changes are client-side UI improvements
-4. **XSS protection maintained**: All user inputs still properly escaped by React
+### WCAG 2.1 AA Accessibility
 
-### Risk Assessment
-- **Risk Level**: 🟢 **LOW**
-- **Breaking Changes**: None
-- **Migration Required**: None
-- **Backend Impact**: None
+- ✅ Axe-core: 0 violations on full page
+- ✅ All interactive elements focusable with visible focus rings
+- ✅ ARIA labels on all controls (combobox, progressbar, dialog, live regions)
+- ✅ Keyboard-only navigation: search → select → delegate → revoke
+- ✅ Focus trap in dialogs (Tab cycling)
+- ✅ Screen reader announcements for search results and toast notifications
+- ✅ Semantic HTML (`<dialog>`, `<ul role="listbox">`, `<dl>`)
 
-### Accessibility Risk Mitigation
-- All changes improve WCAG 2.1 AA compliance
-- No existing accessibility features removed
-- Enhanced keyboard navigation support added
+---
 
-## Branch
+### How to Test
 
 ```bash
-git checkout -b ux11-copy-deck--revenue-share-vs-dividend-vs-payout-t
-```
-
-## Commit Message
-
-```
-ux(frontend): copy deck: revenue share vs dividend vs payout terminology
+# Run tests
+npm test -- src/components/GovernanceDelegation/
 
-- Standardize terminology: RevenueShare (not revenue-share/dividend)
-- Replace "dividends" with "RevenueShare payouts" throughout
-- Add WCAG 2.1 AA accessibility improvements (ARIA, focus states)
-- Create terminology constants file for consistency
-- Add automated validation script for terminology checks
-- Add test coverage for terminology and accessibility
+# Run with coverage
+npm test -- src/components/GovernanceDelegation/ --coverage
 
-Fixes: RC26Q2-F11
+# Lint
+npm run lint
 ```
-
-## Labels
-
-- `ux` (purple: #5319E7)
-- `copy` (orange: #F9D0C4)
-- `accessibility` (green: #0E8A16)
-- `P1` (purple: #5319E7)
-
-## Checklist
-
-- [x] Terminology standardized across all pages
-- [x] "Dividend" term completely removed
-- [x] WCAG 2.1 AA compliance verified
-- [x] ARIA attributes added to all form inputs
-- [x] Focus states enhanced for keyboard navigation
-- [x] Terminology constants file created
-- [x] Automated validation script created
-- [x] Test coverage added
-- [x] ESLint passes (no new errors)
-- [x] No breaking changes
-- [x] Documentation complete
-
-## Reviewers
-
-Please verify:
-1. Terminology consistency across all UI text
-2. Accessibility improvements meet WCAG standards
-3. No prohibited terms remain in the codebase
-4. Focus states work correctly with keyboard navigation
-
----
-
-**Timeframe**: Completed within 96-hour assignment window
-**Test Coverage**: ≥95% for new/changed code paths
-**Documentation**: Complete in-repo documentation provided