diff --git a/plan/01_CORE_MVP/frontend.md b/plan/01_CORE_MVP/frontend.md new file mode 100644 index 0000000..bcabe40 --- /dev/null +++ b/plan/01_CORE_MVP/frontend.md @@ -0,0 +1,317 @@ +# Frontend MVP Implementation Plan + +## Overview +This plan details the concrete implementation steps for the Captain's Log frontend MVP using Vite + React + TypeScript + Tailwind CSS with comprehensive testing infrastructure. + +## Project Structure (Planned Implementation) +``` +captains-log/ +├── justfile # Root task runner with combined commands +├── backend/ +│ ├── justfile # Backend-specific commands +│ └── ... (existing backend structure) +└── frontend/ + ├── justfile # Frontend-specific commands + ├── package.json # Node.js project manifest + ├── vite.config.ts # Vite configuration + ├── tsconfig.json # TypeScript configuration + ├── tailwind.config.js # Tailwind CSS configuration + ├── index.html # Entry HTML file + ├── src/ + │ ├── main.tsx # Application entry point + │ ├── App.tsx # Root component with routing + │ ├── components/ + │ │ ├── TaskCard.tsx # Individual task display + │ │ ├── TaskForm.tsx # Create/edit task form + │ │ ├── TaskList.tsx # Main task list view + │ │ ├── QuickCapture.tsx # Rapid task entry + │ │ └── StatusBadge.tsx # Task status visualization + │ ├── hooks/ + │ │ ├── useTask.ts # Single task operations + │ │ ├── useTasks.ts # Multiple task operations + │ │ └── useApi.ts # Generic API utilities + │ ├── services/ + │ │ └── api.ts # Backend API client + │ ├── types/ + │ │ └── task.ts # TypeScript type definitions + │ └── styles/ + │ └── index.css # Tailwind imports and custom styles + └── tests/ + └── components/ # Component unit tests +``` + +## Phase 1: Project Foundation (Days 1-2) + +### Task 1.1: Initialize Frontend Project +- [ ] **File**: `frontend/package.json` + - Create new Vite + React + TypeScript project + - Add dependencies: react, react-dom, react-router-dom, tailwindcss, @types/* + - Add dev dependencies: vitest, @testing-library/react, @testing-library/jest-dom + - Configure scripts for dev, build, test, lint + - **Expected outcome**: `npm install` succeeds + +### Task 1.2: Setup Build Tools and Configuration +- [ ] **Files**: `frontend/vite.config.ts`, `frontend/tsconfig.json`, `frontend/tailwind.config.js` + - Configure Vite with React plugin and proxy to backend + - Setup TypeScript with strict mode and path aliases + - Configure Tailwind CSS with custom design tokens + - Setup Vitest for testing + - **Expected outcome**: `npm run dev` starts frontend development server + +### Task 1.3: Create Frontend Justfile +- [ ] **File**: `frontend/justfile` + - Commands: `dev-frontend`, `build-frontend`, `test-frontend`, `lint-frontend`, `fmt-frontend` + - Setup proxy configuration for backend API + - **Expected outcome**: `just --list` in frontend directory shows all commands + +### Task 1.4: Update Root Justfile Structure +- [ ] **Files**: `justfile`, `backend/justfile` + - Move existing backend commands to `backend/justfile` + - Create new root justfile with combined commands + - Add concurrent execution for `dev` command (both backend + frontend) + - Include commands: `dev`, `build`, `test`, `test-unit`, `fmt`, `lint` + - **Expected outcome**: `just dev` starts both backend and frontend + +## Phase 2: Core API Integration (Days 3-4) + +### Task 2.1: Define TypeScript Types +- [ ] **File**: `frontend/src/types/task.ts` + - Create Task interface matching backend TaskModel + - Add TaskStatus enum (Todo, Done, Backlog) + - Include API response types and error types + - **Expected outcome**: Type definitions compile without errors + +### Task 2.2: Backend API Client +- [ ] **File**: `frontend/src/services/api.ts` + - Implement API client with fetch wrapper + - Add all task endpoints: GET, POST, PUT, DELETE /api/tasks + - Include error handling and response parsing + - Add request/response logging for development + - **Expected outcome**: API client can communicate with backend + +### Task 2.3: Custom React Hooks for API +- [ ] **Files**: `frontend/src/hooks/useTask.ts`, `frontend/src/hooks/useTasks.ts` + - Create useTask hook for single task operations (get, update, delete) + - Create useTasks hook for task list operations (list, create) + - Include loading states, error handling, and optimistic updates + - Add data caching and synchronization + - **Expected outcome**: Hooks provide clean API for components + +### Task 2.4: API Integration Tests +- [ ] **File**: `frontend/tests/api.test.ts` + - Test API client with mock responses + - Test custom hooks with mock API calls + - Test error handling scenarios + - Use vitest and testing library utilities + - **Expected outcome**: `just test-frontend` passes all API tests + +## Phase 3: Core Components (Days 5-6) + +### Task 3.1: Task Card Component +- [ ] **File**: `frontend/src/components/TaskCard.tsx` + - Display task with title, description, status, dates + - Implement inline editing for title and description + - Add status change buttons/dropdown + - Include delete confirmation + - Mobile-friendly touch interactions + - **Expected outcome**: TaskCard displays and edits tasks correctly + +### Task 3.2: Task Form Component +- [ ] **File**: `frontend/src/components/TaskForm.tsx` + - Create/edit form with all task properties + - Form validation and error display + - Handle form submission with API calls + - Support both modal and inline modes + - **Expected outcome**: TaskForm creates and updates tasks + +### Task 3.3: Quick Capture Component +- [ ] **File**: `frontend/src/components/QuickCapture.tsx` + - Minimal input for rapid task creation + - Auto-focus and keyboard shortcuts + - Optimistic UI updates + - Smart defaults for new tasks + - **Expected outcome**: QuickCapture enables fast task entry + +### Task 3.4: Status Badge Component +- [ ] **File**: `frontend/src/components/StatusBadge.tsx` + - Visual status indicators with colors + - Consistent styling across components + - Accessible color schemes + - **Expected outcome**: StatusBadge provides clear status visualization + +### Task 3.5: Component Unit Tests +- [ ] **Files**: `frontend/tests/components/*.test.tsx` + - Test all components with React Testing Library + - Test user interactions and state changes + - Test API integration through mocked hooks + - Test accessibility basics (aria labels, keyboard navigation) + - **Expected outcome**: All component tests pass + +## Phase 4: Main Application (Days 7-8) + +### Task 4.1: Task List Component +- [ ] **File**: `frontend/src/components/TaskList.tsx` + - Display tasks in organized list/grid layout + - Filter tasks by status (Todo, In Progress, Done, Someday) + - Sort tasks by created date, priority, due date + - Implement virtual scrolling for performance + - **Expected outcome**: TaskList displays tasks efficiently + +### Task 4.2: Main App Component and Routing +- [ ] **Files**: `frontend/src/App.tsx`, `frontend/src/main.tsx` + - Setup React Router with basic navigation + - Create main layout with header and task area + - Implement responsive design with Tailwind + - Add loading states and error boundaries + - **Expected outcome**: Full application loads and navigates properly + +### Task 4.3: State Management and Persistence +- [ ] **File**: `frontend/src/hooks/useApi.ts` + - Implement localStorage for offline task caching + - Add synchronization when coming back online + - Handle conflicting updates gracefully + - Maintain app state across page refreshes + - **Expected outcome**: App works offline and syncs when online + +### Task 4.4: Mobile Responsiveness +- [ ] **Files**: Update all component styles + - Optimize layouts for mobile screens (320px+) + - Add touch gestures for common actions + - Ensure forms work well on mobile keyboards + - Test on various screen sizes + - **Expected outcome**: App is fully usable on mobile devices + +## Phase 5: Polish and Testing (Day 9) + +### Task 5.1: Error Handling and User Feedback +- [ ] **Files**: Update all components + - Add comprehensive error messages + - Implement toast notifications for actions + - Add loading spinners and skeleton screens + - Handle network failures gracefully + - **Expected outcome**: Users get clear feedback for all actions + +### Task 5.2: Performance Optimization +- [ ] **Files**: Review and optimize all components + - Implement React.memo where appropriate + - Optimize re-renders with useCallback/useMemo + - Add code splitting for larger bundles + - Optimize images and assets + - **Expected outcome**: App loads and responds quickly + +### Task 5.3: Comprehensive Testing +- [ ] **Files**: Expand test coverage + - Achieve >80% frontend code coverage + - Test integration between components + - Test error scenarios and edge cases + - Add performance tests if needed + - **Expected outcome**: `just test-frontend` passes with high coverage + +### Task 5.4: Final Integration Testing +- [ ] **Manual testing of full application** + - Test complete user workflows + - Verify backend-frontend integration + - Test on different browsers and devices + - Validate all MVP requirements are met + - **Expected outcome**: Full application works end-to-end + +## Dependencies and Key Technologies + +### Core Dependencies (package.json) +```json +{ + "dependencies": { + "react": "^18.3.0", + "react-dom": "^18.3.0", + "react-router-dom": "^6.26.0" + }, + "devDependencies": { + "@types/react": "^18.3.0", + "@types/react-dom": "^18.3.0", + "@vitejs/plugin-react": "^4.3.0", + "vite": "^5.4.0", + "typescript": "^5.5.0", + "tailwindcss": "^3.4.0", + "vitest": "^2.0.0", + "@testing-library/react": "^16.0.0", + "@testing-library/jest-dom": "^6.5.0" + } +} +``` + +### Testing Tools +- **Unit Tests**: Vitest with React Testing Library +- **Component Tests**: User interaction testing +- **API Tests**: Mock-based testing of hooks and services +- **Coverage**: Vitest coverage reporting + +## Justfile Commands Structure + +### Root Justfile Commands +```just +# Combined commands +dev: dev-backend dev-frontend # Start both servers concurrently +build: build-backend build-frontend +test: test-backend test-frontend +test-unit: test-unit-backend test-unit-frontend +fmt: fmt-backend fmt-frontend +lint: lint-backend lint-frontend + +# Individual service commands +dev-backend: + just backend/dev-backend + +dev-frontend: + just frontend/dev-frontend +``` + +### Backend Justfile (migrated commands) +```just +set working-directory := '.' + +dev-backend: + cargo run + +build-backend: + cargo build + +test-unit-backend: + cargo test +``` + +### Frontend Justfile (new commands) +```just +set working-directory := '.' + +dev-frontend: + npm run dev + +build-frontend: + npm run build + +test-frontend: + npm test + +lint-frontend: + npm run lint +``` + +## Success Criteria +- [ ] All CRUD operations work through the UI +- [ ] Mobile-responsive design functions well +- [ ] >80% frontend code coverage achieved +- [ ] Integration with backend API is seamless +- [ ] Quick capture enables rapid task entry +- [ ] Task list filtering and sorting work correctly +- [ ] Offline functionality with sync capabilities +- [ ] Error handling provides clear user feedback +- [ ] Performance is acceptable for MVP usage + +## Testing Strategy Summary +1. **Unit Tests**: Component testing with React Testing Library and Vitest +2. **Integration Tests**: API hook testing with mock backend +3. **Manual Testing**: Cross-browser and mobile device validation +4. **Coverage**: Automated coverage reporting with Vitest +5. **Performance**: Basic performance validation during development + +This plan provides a comprehensive roadmap for implementing a robust, well-tested frontend MVP that integrates seamlessly with the existing backend API and meets all requirements outlined in the original plan.md. \ No newline at end of file