docs/frontend-implementation-guide.md

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

// 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:

// 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

// 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:

// 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 - Full analysis
• Backend Audit Report - Comparison
• Lessons Learned - Best practices
• ARCHITECTURE.md - System architecture

---

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