diff --git a/docs/superpowers/plans/2026-04-03-phase2-online-board.md b/docs/superpowers/plans/2026-04-03-phase2-online-board.md new file mode 100644 index 00000000..5f3c4759 --- /dev/null +++ b/docs/superpowers/plans/2026-04-03-phase2-online-board.md @@ -0,0 +1,225 @@ +# Phase 2: Online Board Feature + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Implement the Online Board feature -- the main flight status display with search by flight number, route, departure, or arrival. Includes start page, search results, and flight details. + +**Architecture:** Feature-isolated module at `src/features/online-board/` with hooks, components, and services. Uses TanStack Query hooks from shared layer. URL-driven state with route validation. + +**Tech Stack:** React 19, TanStack Query v5, Zustand, PrimeReact (Accordion, AutoComplete, Calendar), react-i18next, CSS Modules + +**Depends on:** Phase 1 Foundation (complete) + +--- + +### Task 1: Online Board Feature Hooks + +**Files:** +- Create: `react-app/src/features/online-board/hooks/useOnlineBoardApi.ts` +- Create: `react-app/src/features/online-board/hooks/useFlightNavigation.ts` +- Create: `react-app/src/features/online-board/hooks/index.ts` + +Feature-specific hooks wrapping shared query hooks with online-board-specific logic. + +- [ ] **Step 1: Create API hook** + +`useOnlineBoardApi.ts` wraps the shared query hooks with board-specific params and adds the `getFlightDaysByNumber` and `getFlightDaysByRoute` calls for calendar disabled dates. + +- [ ] **Step 2: Create navigation hook** + +`useFlightNavigation.ts` provides `navigateToSearch`, `navigateToDetails`, `navigateToStart` using React Router's `useNavigate` with URL builders from shared utils. + +- [ ] **Step 3: Commit** + +--- + +### Task 2: Search Filter Components + +**Files:** +- Create: `react-app/src/features/online-board/components/filter/FlightNumberFilter.tsx` +- Create: `react-app/src/features/online-board/components/filter/FlightNumberFilter.module.css` +- Create: `react-app/src/features/online-board/components/filter/RouteFilter.tsx` +- Create: `react-app/src/features/online-board/components/filter/RouteFilter.module.css` +- Create: `react-app/src/features/online-board/components/filter/OnlineBoardFilter.tsx` +- Create: `react-app/src/features/online-board/components/filter/OnlineBoardFilter.module.css` + +PrimeReact Accordion with 2 tabs: Flight Number search and Route search. + +- [ ] **Step 1: Create FlightNumberFilter** + +Input fields: flight number (SU prefix + 4 digits + optional suffix letter), date picker. Validates input, calls API for disabled dates. + +- [ ] **Step 2: Create RouteFilter** + +Input fields: departure autocomplete, arrival autocomplete, swap button, date picker, time range. Validates stations, calls API for disabled dates. + +- [ ] **Step 3: Create OnlineBoardFilter (accordion wrapper)** + +PrimeReact Accordion with 2 panels. Manages active tab state. + +- [ ] **Step 4: Commit** + +--- + +### Task 3: Flight Display Components + +**Files:** +- Create: `react-app/src/features/online-board/components/board/FlightCard.tsx` +- Create: `react-app/src/features/online-board/components/board/FlightCard.module.css` +- Create: `react-app/src/features/online-board/components/board/FlightList.tsx` +- Create: `react-app/src/features/online-board/components/board/FlightList.module.css` +- Create: `react-app/src/features/online-board/components/board/FlightStatusBadge.tsx` + +Components to display flight search results. + +- [ ] **Step 1: Create FlightStatusBadge** + +Renders colored badge based on FlightStatus enum (green=arrived, orange=delayed, red=cancelled, etc.) + +- [ ] **Step 2: Create FlightCard** + +Expandable card showing: departure/arrival times, cities, airline, status. Click to expand shows leg details. Uses PrimeReact Card. + +- [ ] **Step 3: Create FlightList** + +Renders list of FlightCards. Highlights closest flight to search time. Manages expanded state. + +- [ ] **Step 4: Commit** + +--- + +### Task 4: Flight Details Components + +**Files:** +- Create: `react-app/src/features/online-board/components/details/FlightDetails.tsx` +- Create: `react-app/src/features/online-board/components/details/FlightDetails.module.css` +- Create: `react-app/src/features/online-board/components/details/FlightLegDetails.tsx` +- Create: `react-app/src/features/online-board/components/details/FlightLegDetails.module.css` +- Create: `react-app/src/features/online-board/components/details/FlightMiniList.tsx` +- Create: `react-app/src/features/online-board/components/details/FlightMiniList.module.css` + +Components for the flight details page. + +- [ ] **Step 1: Create FlightLegDetails** + +Per-leg detail panel: departure/arrival info, times (scheduled/estimated/actual), gate, terminal, boarding status, transfer info. + +- [ ] **Step 2: Create FlightMiniList** + +Left sidebar list of all matching flights. Highlights selected. Click emits selection change. + +- [ ] **Step 3: Create FlightDetails** + +Main details view. For direct flights: single FlightLegDetails. For multi-leg: timeline with FlightLegDetails per leg + transfer segments. + +- [ ] **Step 4: Commit** + +--- + +### Task 5: Start Page + +**Files:** +- Create: `react-app/src/features/online-board/components/StartPage.tsx` +- Create: `react-app/src/features/online-board/components/StartPage.module.css` +- Modify: `react-app/src/features/online-board/components/OnlineBoard.tsx` + +- [ ] **Step 1: Create StartPage** + +Renders: page title, OnlineBoardFilter (search form), hero section with 4 info tiles, PopularRequests widget. Uses MetaTags for SEO. + +- [ ] **Step 2: Update OnlineBoard entry component** + +Replace placeholder with router that renders StartPage on `/onlineboard` and other pages on sub-routes. + +- [ ] **Step 3: Commit** + +--- + +### Task 6: Search Results Page + +**Files:** +- Create: `react-app/src/features/online-board/components/SearchPage.tsx` +- Create: `react-app/src/features/online-board/components/SearchPage.module.css` +- Create: `react-app/src/ui/date-tabs/DateTabs.tsx` +- Create: `react-app/src/ui/date-tabs/DateTabs.module.css` +- Create: `react-app/src/ui/time-selector/TimeSelector.tsx` +- Create: `react-app/src/ui/time-selector/TimeSelector.module.css` + +Shared search results page for all 4 search types (flight number, route, departure, arrival). + +- [ ] **Step 1: Create DateTabs component** + +Horizontal date navigation (today, tomorrow, +2, etc.) with disabled dates. Sticky at top. + +- [ ] **Step 2: Create TimeSelector component** + +Time range picker (from/to sliders or inputs). + +- [ ] **Step 3: Create SearchPage** + +Receives search type and params. Renders: DateTabs, TimeSelector, FlightList, loading/empty states. Calls useFlightsQuery with params. Handles date/time changes via URL navigation. + +- [ ] **Step 4: Commit** + +--- + +### Task 7: Flight Details Page + +**Files:** +- Create: `react-app/src/features/online-board/components/DetailsPage.tsx` +- Create: `react-app/src/features/online-board/components/DetailsPage.module.css` + +- [ ] **Step 1: Create DetailsPage** + +Renders: DateTabs, FlightMiniList (sidebar), FlightDetails (main). Fetches flight details via useFlightDetailsQuery. Handles flight selection from mini-list. Uses MetaTags + FlightJsonLd for SEO. + +- [ ] **Step 2: Commit** + +--- + +### Task 8: Route Definitions with Validation + +**Files:** +- Create: `react-app/src/features/online-board/components/ValidatedRoute.tsx` +- Modify: `react-app/src/routes/onlineboard/page.tsx` +- Create: `react-app/src/routes/onlineboard/flight.[params].tsx` +- Create: `react-app/src/routes/onlineboard/departure.[params].tsx` +- Create: `react-app/src/routes/onlineboard/arrival.[params].tsx` +- Create: `react-app/src/routes/onlineboard/route.[params].tsx` +- Create: `react-app/src/routes/onlineboard/[params].tsx` + +- [ ] **Step 1: Create ValidatedRoute wrapper** + +Generic wrapper that validates URL params, redirects to 404 on invalid. + +- [ ] **Step 2: Create route pages** + +Each route page: parses params, validates, renders SearchPage or DetailsPage with appropriate type. + +- [ ] **Step 3: Verify all routes work** + +Test: `/onlineboard`, `/onlineboard/flight/1234-2026-04-03`, `/onlineboard/route/SVO-LED-2026-04-03-08002200`, `/onlineboard/SU1234-2026-04-03` + +- [ ] **Step 4: Commit** + +--- + +### Task 9: Build Verification + +- [ ] **Step 1: Run production build** + +Verify build succeeds with all new components. + +- [ ] **Step 2: Final commit** + +--- + +## What This Plan Produces + +After completing all 9 tasks: +- Complete Online Board feature with start page, 4 search result types, and flight details +- Reusable UI components (DateTabs, TimeSelector) +- Flight display components (FlightCard, FlightList, FlightDetails) +- Search filter form with flight number and route tabs +- URL-driven routing with param validation +- SEO (MetaTags + JSON-LD) on all pages