# Frontend Refactoring Implementation Guide

**Based on:** Frontend Audit Report (2025-11-09)  
**Priority:** High Priority (Quick Wins)  
**Estimated Time:** 4 hours  
**Expected LOC Savings:** ~220 LOC

---

## ✅ Completed (Phase 1)

### New Files Created:

1. **`frontend/src/lib/apiClient.ts`** (170 LOC)
   - Centralized API client with type-safe methods
   - Error classification (NETWORK, NOT_FOUND, VALIDATION, SERVER)
   - Localized error messages
   - Convenience helpers: `loadContent()`, `loadContentWithError()`

2. **`frontend/src/hooks/useApiData.ts`** (110 LOC)
   - Custom hook for data fetching
   - Automatic loading/error state management
   - Refetch capability
   - Two variants: `useApiData()` and `useApiDataWithError()`

3. **`frontend/src/state/modules/toast.ts`** (70 LOC)
   - Zustand store for toast notifications
   - Queue management
   - Auto-hide after duration
   - Convenience methods: `toast.success()`, `toast.error()`, etc.

4. **`frontend/src/components/ToastContainer.tsx`** (30 LOC)
   - Toast UI component
   - Supports all toast types (success, error, info, warning)
   - Click to dismiss

5. **Tests** (3 files, ~250 LOC):
   - `frontend/tests/apiClient.test.ts` (95 LOC)
   - `frontend/tests/useApiData.test.ts` (85 LOC)
   - `frontend/tests/toast.test.ts` (70 LOC)

6. **Styles:**
   - Added toast CSS to `frontend/src/styles.css` (90 LOC)

7. **i18n:**
   - Added error messages to `frontend/src/i18n/cs.json`
   - Added tips translations

8. **Example Refactoring:**
   - `frontend/src/views/TipsView.refactored.tsx` (69 LOC)
   - Shows how to use new utilities
   - 20 LOC saved compared to original

**Total Created:** ~550 LOC (utilities) + ~250 LOC (tests) = 800 LOC

---

## 🚀 Next Steps (Phase 2)

### Step 1: Integrate ToastContainer into App

```typescript
// frontend/src/App.tsx
import ToastContainer from './components/ToastContainer'

function App() {
  return (
    <div className="app">
      <ToastContainer />
      {/* ... rest of app */}
    </div>
  )
}
```

### Step 2: Refactor Views to Use New Utilities

**Priority order:**

1. ✅ **TipsView.tsx** (example already created)
2. **ActivitiesView.tsx** (~15 LOC saved)
3. **MeditationsView.tsx** (~18 LOC saved)
4. **SelfReturnView.tsx** (~20 LOC saved)
5. **AttachmentStylesView.tsx** (~12 LOC saved)

**Refactoring pattern:**

```typescript
// BEFORE:
const [data, setData] = useState([])
const [loading, setLoading] = useState(true)
const [toast, setToast] = useState<string | null>(null)

useEffect(() => {
  fetch('/api/content/tips')
    .then(res => res.json())
    .then(data => setData(data.tips || []))
    .catch(() => setData([]))
    .finally(() => setLoading(false))
}, [])

useEffect(() => {
  if (!toast) return
  const timer = setTimeout(() => setToast(null), 3000)
  return () => clearTimeout(timer)
}, [toast])

// AFTER:
const { data: tipsContent, loading } = useApiData({
  url: '/api/content/tips',
  fallback: { tips: [] }
})

const tips = tipsContent.tips

// Replace setToast() with:
import { toast } from '../state/modules/toast'
toast.success('Message here')
```

### Step 3: Refactor ProfileView

ProfileView.tsx is the largest file (798 LOC) and needs special attention.

**Plan:**
1. Extract `NoContactSection.tsx` (~150 LOC)
2. Extract `MedalsSection.tsx` (~200 LOC)
3. Use `useApiData` for medals loading
4. Use toast store for notifications

**Expected result:** ProfileView.tsx: 798 → ~450 LOC

### Step 4: Add Error Boundaries

```typescript
// frontend/src/components/ErrorBoundary.tsx
export class ErrorBoundary extends React.Component {
  componentDidCatch(error: Error) {
    toast.error(t('errors.unknown'))
    console.error('ErrorBoundary caught:', error)
  }
}
```

### Step 5: Update Tests

Add integration tests for refactored views:

```typescript
// frontend/tests/TipsView.integration.test.tsx
describe('TipsView integration', () => {
  it('should load and display tips', async () => {
    render(<TipsView accent="#667eea" />)
    await waitFor(() => {
      expect(screen.getByText('Rychlé tipy')).toBeInTheDocument()
    })
  })
})
```

---

## 📊 Expected Results

### LOC Changes:
```
Phase 1 (Completed):
  New utilities created:  +550 LOC
  New tests created:      +250 LOC
  Total created:          +800 LOC

Phase 2 (To Do):
  Views refactored:       -220 LOC (duplicates eliminated)
  ProfileView split:      -100 LOC (better organization)
  Total eliminated:       -320 LOC

Net change:               +480 LOC (architectural investment)
```

### Quality Improvements:
- ✅ Consistent error handling
- ✅ Type-safe API calls
- ✅ Centralized toast management
- ✅ Reusable data fetching patterns
- ✅ Better testability
- ✅ Cleaner component code

### Test Coverage:
- ✅ 3 new utility test files
- 🔄 5-10 integration tests to add
- 🔄 Update existing tests for refactored views

---

## 🔄 Migration Checklist

For each view being refactored:

- [ ] Replace `fetch()` with `useApiData()`
- [ ] Remove `useState` for loading/error
- [ ] Replace local toast logic with `toast.*` functions
- [ ] Update imports
- [ ] Add/update tests
- [ ] Verify functionality in browser
- [ ] Check for console errors
- [ ] Update documentation

---

## 🎯 Success Criteria

Phase 2 is complete when:

1. ✅ All 5 priority views use `useApiData`
2. ✅ All toast notifications use toast store
3. ✅ No duplicated fetch/loading/error patterns
4. ✅ ProfileView split into sub-components
5. ✅ All tests passing (277 backend + 90+ frontend)
6. ✅ No console errors in development
7. ✅ Documentation updated

---

## 📝 Notes

### API Client Benefits:
- Centralized error handling
- Consistent retry logic (future)
- Request/response logging (future)
- Type safety across app

### useApiData Benefits:
- Eliminates 10-15 LOC per view
- Consistent loading states
- Easy to add features (caching, retries)

### Toast Store Benefits:
- Eliminates 8-12 LOC per view
- Consistent UX
- Queue management
- Easy to extend

### Why This Matters:
Frontend is already well-structured. These changes:
- Remove remaining duplicates
- Improve consistency
- Make future features easier
- Better align with backend patterns

---

## 🔗 Related Documents

- [Frontend Audit Report](./frontend-audit-report.md) - Full analysis
- [Backend Audit Report](./backend-audit-report.md) - Comparison
- [Lessons Learned](./lessons-learned.md) - Best practices
- [ARCHITECTURE.md](./ARCHITECTURE.md) - System architecture

---

**Next Action:** Review with team, then start Phase 2 refactoring