# 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`
```typescript
export class LeagueSeasonSummaryDTO {
  // ... existing fields
  @ApiProperty()
  totalRaces!: number;

  @ApiProperty()
  completedRaces!: number;

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

### `LeagueStandingDTO`
```typescript
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`)
```typescript
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.