diff --git a/docs/superpowers/plans/2026-04-23-p5-flight-cards-timeline.md b/docs/superpowers/plans/2026-04-23-p5-flight-cards-timeline.md new file mode 100644 index 00000000..362dd6b8 --- /dev/null +++ b/docs/superpowers/plans/2026-04-23-p5-flight-cards-timeline.md @@ -0,0 +1,239 @@ +# P5 — Flight Cards + Timeline + Aircraft Icons + "Уточняется" Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` (recommended) or `superpowers:executing-plans`. + +**Goal:** Bring §4.1.15 (Online-Board flight-card details), §4.1.16 (Schedule flight-card details), §4.1.17 (day-change algorithm), §4.1.22 (aircraft icon algorithm), §4.1.23 ("Уточняется" fallback) into compliance. + +**Architecture:** Flight-details pages + components already exist from phase-1 and were extensively iterated during P1–P4. P5 is primarily an audit pass against TZ Tables 42+ for per-structure-form content. + +**Tech Stack:** TypeScript, React 18, Vitest + RTL. + +**Parent spec:** `docs/superpowers/specs/2026-04-21-online-board-schedule-tz-redesign-design.md`. + +**Target rule count:** §4.1.15 ≥100, §4.1.16 ≥120, §4.1.17 ≥5, §4.1.22 ≥10, §4.1.23 ≥5. + +--- + +## File Structure + +### Files to create +- `src/features/online-board/timelineTime.ts` + test — §4.1.15.7 time-calculation algorithm for timeline. +- `src/features/online-board/previousFlight.ts` + test — §4.1.15.9 previous-flight algorithm. +- `src/shared/flightStatusDisplay.ts` + test — §4.1.15.8 status-on-timeline display rules. +- `src/shared/aircraftIcon.ts` + test — §4.1.22 aircraft-icon mapping algorithm. +- `src/shared/tbd.ts` + test — §4.1.23 `"Уточняется"` fallback helper. + +### Files to modify +- `src/features/online-board/components/OnlineBoardDetailsPage.tsx` +- `src/features/online-board/components/FlightSchedule/*` — direct-flight timeline +- `src/features/online-board/components/FullRouteTimeline/*` — multi-segment +- `src/features/online-board/components/TransferBar/*` — connecting flights + intermediate-landing +- `src/features/online-board/components/BoardDetailsHeader/*` +- `src/features/online-board/components/FlightsMiniList/*` +- `src/features/online-board/components/DetailsBackButton/*` +- `src/features/online-board/components/details-panels/*` +- `src/features/schedule/components/ScheduleDetailsPage.tsx` +- `src/features/schedule/components/ScheduleFlightBody.tsx` (reused for some details views) +- `src/i18n/locales/*/common.json` — i18n updates +- spec file + +--- + +## Task 1: Populate §4.1.15/16/17/22/23 rules + +Use same pattern as P1/P2/P3/P4 Task 1. + +TZ line ranges: +- §4.1.15: ~1927 to ~2308 +- §4.1.16: ~2309 to ~2886 +- §4.1.17: ~2887 to ~2907 +- §4.1.22: ~2985 to ~3040 +- §4.1.23: ~3041 to ~3049 + +Append rule rows. Status=TBD, Plan=P5. + +Commit: `Populate rule rows for P5 subsections 4.1.15/16/17/22/23 in TZ audit spec`. + +--- + +## Task 2: `"Уточняется"` fallback helper (§4.1.23) + +Tiny, isolated. Create `src/shared/tbd.ts`: + +```ts +/** + * Fallback display per TZ §4.1.23: when a field is missing from the API + * response, show the localized "Уточняется" label instead of an empty + * or dash value. + */ + +// eslint-disable-next-line @typescript-eslint/no-explicit-any +type TFunction = (key: string, opts?: any) => string; + +export function tbdOr(value: T | null | undefined, t: TFunction): T | string { + if (value === null || value === undefined) return t("SHARED.TBD"); + if (typeof value === "string" && value.trim() === "") return t("SHARED.TBD"); + return value; +} +``` + +Add `SHARED.TBD` i18n key: ru = `"Уточняется"`, en = `"Pending"`, others empty. + +Add test. + +Commit: `Add "Уточняется" fallback helper per TZ 4.1.23`. + +--- + +## Task 3: Aircraft icon mapping (§4.1.22) + +Create `src/shared/aircraftIcon.ts` + test that maps an IATA/ICAO aircraft-type code to an icon asset. + +Per TZ: +- Map from aircraft type code → icon asset path. +- Fall back to generic icon when unknown. +- Icon has `title` / tooltip with aircraft-type name. + +Enumerate the TZ mapping (TZ likely has a table). Check if existing code has a mapping to reuse. + +Commit: `Add aircraft-icon mapping algorithm per TZ 4.1.22`. + +--- + +## Task 4: Day-change algorithm (§4.1.17) + +§4.1.17 is already partially implemented (commit `d942cb5` for IFlyWarning, earlier commits for dayChange badges). Audit existing `dayChange` logic: +- `dayChange = (arrLocalDate − depLocalDate) in whole days`, using each airport's local TZ. +- Applies consistently across results, details, mini-list. + +Create `src/features/online-board/dayChange.ts` (or use existing if present) + test with comprehensive cases (including negative dayChange, +2 days, etc.). + +Commit: `Verify day-change algorithm per TZ 4.1.17`. + +--- + +## Task 5: Timeline time-calculation algorithm (§4.1.15.7) + +Per TZ §4.1.15.7: which time to show on the timeline at each block — scheduled vs estimated vs actual, with status-driven selection. + +Create `src/features/online-board/timelineTime.ts` + test covering all status branches. + +Wire into `FlightSchedule` / `FullRouteTimeline`. + +Commit per logical cluster. + +--- + +## Task 6: Timeline status display (§4.1.15.8) + +Per TZ §4.1.15.8: enumerate status states and their visual display rules (colors, labels, icon states). + +Audit existing `FlightStatus.tsx` and `details-panels/`. Add missing states. + +Commit. + +--- + +## Task 7: Previous-flight algorithm (§4.1.15.9) + +Per TZ §4.1.15.9: how the "was previously" chip is populated (look up prior leg of the same aircraft). + +Create `src/features/online-board/previousFlight.ts` + test + wire into details header. + +Commit. + +--- + +## Task 8: Flight details — direct flight (§4.1.15.4) + +Audit `OnlineBoardDetailsPage` rendering for direct flights: carrier, aircraft, from-to, times, terminal, gate, live status ladder (registration/boarding/deboarding blocks), on-board meals (§4.1.15.10), on-board services (§4.1.15.11). + +Fix gaps. + +Commit per cluster. + +--- + +## Task 9: Flight details — multi-segment (§4.1.15.5 + §4.1.16.5) + +Per-leg breakdown, FullRouteTimeline visualization. + +Fix gaps. + +Commit. + +--- + +## Task 10: Flight details — connecting (§4.1.16.6) + +Multiple flight numbers, transfer-time display, walk-between-gates visuals, `TransferBar` audit. + +Fix gaps. + +Commit. + +--- + +## Task 11: Intermediate landing + transfer (§4.1.15.6 + §4.1.16.7) + +Same flight number, stop at intermediate airport, landed/took-off substates. Distinct from transfer (different flight number). + +Fix gaps. + +Commit. + +--- + +## Task 12: Execution-days algorithm (§4.1.16.8) + +Schedule-specific: weekday mask derived from schedule rules. + +Audit existing impl + test. + +Commit. + +--- + +## Task 13: Structure of details page (§4.1.15.1 + §4.1.16.1) + +Verify page layout: header, mini-list, day tabs, main content, footer. + +Commit. + +--- + +## Task 14: Mini-list (§4.1.15.2 + §4.1.16.2) + +Audit `FlightsMiniList` composition, click behavior, selected-item styling. + +Commit. + +--- + +## Task 15: Day tabs in details (§4.1.15.3 + §4.1.16.3) + +Audit day-tab behavior on details page (filtered to this flight number). + +Commit. + +--- + +## Task 16: Update spec + merge gate + +Mark P5 rules Done. Merge. + +--- + +## Self-Review + +**1. Spec coverage.** All P5 subsections have a dedicated task. + +**2. Placeholder scan.** Task 1 populates rule IDs; audit tasks find gaps. Standard P4-style audit plan. + +**3. Type consistency.** `tbdOr` / `aircraftIconFor(code)` / `previousFlightOf(flight)` named consistently. + +--- + +## Execution Handoff + +P5 is large — scope per-task and commit frequently.