gridpilot.gg/plans/league-pages-enhancement.md

Plan: League Pages Enhancement

1. Analysis of Current State

Leagues Discovery Page (/leagues)

• Current: Basic grid of league cards with search and category filters.
• Gaps:
  • No "Featured" or "Promoted" leagues section.
  • Limited metadata in cards (missing next race info, active season status).
  • No "Quick Join" or "Follow" actions directly from the list.
  • Categories are hardcoded in the client.

League Detail Page (/leagues/[id])

• Current: Tabbed layout (Overview, Schedule, Standings, Roster, Rulebook).
• Gaps:
  • Overview: Very static. Missing "Next Race" countdown, "Recent Results" snippet, and "Active Season" progress.
  • Schedule: Simple list. Missing "Register" buttons for upcoming races, "View Results" for past races.
  • Standings: Basic table. Missing "Trend" indicators (up/down positions), "Last Race" points.
  • Roster: Simple list. Missing driver stats (rating, safety, performance).
  • Functionality: No "Join League" flow visible in the current barebones implementation (though components exist).

2. Proposed Enhancements

A. Leagues Discovery Page

• Featured Section: Add a top section for high-utilization or promoted infrastructure.
• Enhanced Cards: Include "Next Race" date and "Active Drivers" count.
• Dynamic Categories: Move category definitions to the API or a shared config.

B. League Overview (The "Command Center")

• Next Race Widget: High-visibility countdown to the next scheduled event with a "Register" button.
• Season Progress: Visual bar showing how far along the current season is (e.g., "Race 4 of 12").
• Recent Results Snippet: Top 3 from the last completed race.
• Activity Feed: Integration of LeagueActivityFeed component to show recent joins, results, and announcements.
• Wallet & Sponsorship Preview: For admins, show a summary of league funds and active sponsorship slots using LeagueSponsorshipsSection.
• Stewarding Quick-View: Show pending protests count and a link to the stewarding queue.

C. League Schedule

• Interactive Timeline: Group races by month or season.
• Actionable Items: "Register" for upcoming, "View Results" for completed.
• Race Detail Modals: Use RaceDetailTemplate or a modal to show track details, weather, and car classes.
• Admin Controls: Inline "Edit" or "Reschedule" buttons for authorized users.

D. League Standings

• Trend Indicators: Show position changes since the last race.
• Championship Stats: Integrate LeagueChampionshipStats for wins, podiums, and average finish.
• Team Standings: Ensure team-based championships are togglable.
• Drop Weeks Visualization: Clearly mark which races are currently being dropped from a driver's total.

E. League Roster

• Driver Cards: Use a more detailed card format showing GridPilot Rating and recent form.
• Admin Actions: Quick access to "Promote", "Remove", or "Message" for authorized users.
• Join Requests: Integrated JoinRequestsPanel for admins to manage pending applications.

F. Rulebook & Governance

• Structured Rules: Use LeagueRulesPanel to display code of conduct and sporting regulations.
• Governance Transparency: Show the stewarding decision mode (Committee vs Single Steward) using LeagueStewardingSection.

3. UI/UX & Design Streamlining

• Telemetry Aesthetic: Align all league pages with the "Modern Precision" theme (Deep Graphite, Primary Blue, Performance Green).
• Consistent Primitives: Ensure all components use the established UI primitives (Surface, Stack, Text, Icon).
• Responsive Density: Maintain high data density on desktop while ensuring readability on mobile.

4. Data & API Requirements

Core/API Additions

• Next Race Info: API should return the single next upcoming race for a league in the summary/detail DTO.
• Season Progress: Add totalRaces and completedRaces to the LeagueSeasonSummaryDTO.
• Standings Trends: Add positionChange (number) and lastRacePoints (number) to LeagueStandingDTO.
• Activity Feed: Ensure the /leagues/[id]/activity endpoint is fully functional.

View Model Updates

• LeagueSummaryViewModel: Add nextRaceAt, activeDriversCount.
• LeagueDetailViewData: Add nextRace, seasonProgress, recentResults.

5. Proposed DTO Changes (Technical)

LeagueSeasonSummaryDTO

export class LeagueSeasonSummaryDTO {
  // ... existing fields
  @ApiProperty()
  totalRaces!: number;

  @ApiProperty()
  completedRaces!: number;

  @ApiProperty({ required: false })
  nextRaceAt?: Date;
}

LeagueStandingDTO

export class LeagueStandingDTO {
  // ... existing fields
  @ApiProperty({ description: 'Position change since last race' })
  positionChange!: number;

  @ApiProperty({ description: 'Points earned in the last race' })
  lastRacePoints!: number;

  @ApiProperty({ type: [String], description: 'IDs of races that were dropped' })
  droppedRaceIds!: string[];
}

LeagueSummaryDTO (or LeagueWithCapacityAndScoringDTO)

export class LeagueWithCapacityAndScoringDTO {
  // ... existing fields
  @ApiProperty({ required: false })
  pendingJoinRequestsCount?: number;

  @ApiProperty({ required: false })
  pendingProtestsCount?: number;

  @ApiProperty({ required: false })
  walletBalance?: number;
}

6. Implementation Steps (Todo List)

• Phase 1: Data Foundation

  • Update LeagueDetailData and LeagueDetailViewData interfaces.
  • Enhance LeagueDetailViewDataBuilder to compute next race and season progress.
  • (Optional) Add mock data to LeagueService for new fields if API isn't ready.

• Phase 2: Overview Page Overhaul

  • Implement "Next Race" countdown widget.
  • Add "Season Progress" component.
  • Integrate LeagueActivityFeed.

• Phase 3: Schedule & Standings Polish

  • Update LeagueScheduleTemplate with registration actions.
  • Enhance LeagueStandingsTemplate with trend indicators and stats.

• Phase 4: Discovery Page Refinement

  • Update LeaguesTemplate with a "Featured" section.
  • Enhance LeagueCard with more metadata.

• Phase 5: Final Streamlining

  • Audit all league pages for theme consistency.
  • Ensure mobile responsiveness across all new widgets.