@pitvox/partner-react 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,8 @@
 # @pitvox/partner-react
 
-React SDK for PitVox partner websites. Provides hooks, components, and complete leaderboard + competition experiences for sim racing communities affiliated with [PitVox](https://pitvox.com).
+React SDK for PitVox partner websites. Provides hooks, styled components, and a driver dashboard for sim racing communities affiliated with [PitVox](https://pitvox.com).
+
+**Hooks-first**: Use the data hooks with any UI framework (Tailwind, DaisyUI, Shadcn, Preline, etc.). The styled `pvx-*` components are optional building blocks for quick starts.
 
 ## Installation
 
@@ -10,10 +12,8 @@ npm install @pitvox/partner-react
 
 ### Peer dependencies
 
-The SDK requires these in your project:
-
 ```bash
-npm install react react-dom @tanstack/react-query react-router-dom
+npm install react react-dom @tanstack/react-query
 ```
 
 ## Quick start
@@ -25,14 +25,12 @@ import { PitVoxPartnerProvider } from '@pitvox/partner-react'
 
 function App() {
   return (
-    <BrowserRouter>
-      <PitVoxPartnerProvider
-        partnerSlug="your-slug"
-        getSteamId={() => currentUser?.steamId ?? null}
-      >
-        {/* your app */}
-      </PitVoxPartnerProvider>
-    </BrowserRouter>
+    <PitVoxPartnerProvider
+      partnerSlug="your-slug"
+      getSteamId={() => currentUser?.steamId ?? null}
+    >
+      {/* your app */}
+    </PitVoxPartnerProvider>
   )
 }
 ```
@@ -41,48 +39,7 @@ function App() {
 
 ## Leaderboards
 
-### Drop-in (recommended)
-
-One component gives you a complete 4-layer leaderboard with game tabs, version selector, tag filtering, sortable columns, sector highlighting, and drill-down navigation:
-
-```jsx
-import { LeaderboardExplorer } from '@pitvox/partner-react'
-import '@pitvox/partner-react/styles.css'
-
-function LeaderboardsPage() {
-  return <LeaderboardExplorer />
-}
-```
-
-The `LeaderboardExplorer` manages all state via URL search parameters (`?game=evo&track=...&car=...&driver=...`), so deep-linking and browser back/forward work out of the box.
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | — | Additional class on root container |
-| `defaultGame` | `'evo' \| 'acc'` | `'evo'` | Default game tab |
-| `title` | `string` | `'Leaderboards'` | Page heading |
-
-### Layer components
-
-For more control, use the individual layer components directly. Each handles its own sorting, filtering, and highlighting logic:
-
-```jsx
-import { TracksTable, CarsTable, DriversTable, LapHistoryTable } from '@pitvox/partner-react'
-import '@pitvox/partner-react/styles.css'
-```
-
-- **`<TracksTable>`** — Layer 1: all tracks with record holders, tag filtering
-- **`<CarsTable>`** — Layer 2: cars for a selected track, tag filtering
-- **`<DriversTable>`** — Layer 3: drivers for a car with sectors (S1/S2/S3), tyre, fuel
-- **`<LapHistoryTable>`** — Layer 4: driver's lap history with validity and personal best highlighting
-
-You're responsible for wiring up the navigation between layers and managing URL state.
-
-### Hooks only
-
-For fully custom UIs, use the data hooks directly:
+### Hooks
 
 ```jsx
 import {
@@ -96,12 +53,11 @@ import {
 
 **`useLeaderboardIndex(options?)`** — Fetch all tracks with record holders.
 - `options.game` — Filter by game (`'evo'` | `'acc'`)
-- `options.gameVersion` — Filter by EVO version
-- Returns `{ data: Track[], isLoading, partner, generatedAt, totalLaps, totalUsers, versions }`
+- Returns `{ data: Track[], isLoading, generatedAt, totalLaps, totalUsers, versions }`
 
 **`useTrackLeaderboard(trackId, layout?, options?)`** — Fetch track entries.
-- Without `options.carId`: returns best lap per car (Layer 2)
-- With `options.carId`: returns all drivers for that car (Layer 3)
+- Without `options.carId`: returns best lap per car (car-level)
+- With `options.carId`: returns all drivers for that car (driver-level)
 - Returns `{ data: Entry[], isLoading, error }`
 
 **`useDriverLaps(userId, trackId, layout, carId, options?)`** — Fetch a driver's lap history.
@@ -112,58 +68,25 @@ import {
 
 **`useCarMetadata()`** — Returns `{ tags: string[], cars: Record<string, { tags }> }` for tag filtering.
 
-## Competitions
-
-### Drop-in (recommended)
-
-One component gives you a complete competition experience with card grid, championship standings, round-by-round results with session tabs, and entry lists:
-
-```jsx
-import { CompetitionExplorer } from '@pitvox/partner-react'
-import '@pitvox/partner-react/styles.css'
-
-function CompetitionsPage() {
-  return <CompetitionExplorer />
-}
-```
-
-The `CompetitionExplorer` manages all state via URL search parameters (`?competition=abc123&tab=standings&round=2`), so deep-linking and browser back/forward work out of the box.
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `className` | `string` | — | Additional class on root container |
-| `title` | `string` | `'Competitions'` | Page heading |
-
-**Features:**
-- Competition card grid with poster images, type badges, format/car pills, schedule summary, registration status
-- Championship standings with position rank badges, nation flags, wins/podiums columns, per-round cells with dropped round styling
-- Round results with session tabs (Practice/Qualifying/Race), best lap with sector hover tooltip, podium highlighting
-- Entry list with driver avatars
-- Horizontal schedule strip with next-round highlighting
-- Breadcrumb navigation between list and detail views
-
-### Layer components
+### Styled components
 
-For more control, use the individual layer components directly:
+For building leaderboard pages with the SDK's `pvx-*` styles:
 
 ```jsx
-import { CompetitionCards, StandingsTable, RoundResults, EntryList } from '@pitvox/partner-react'
+import { TracksTable, CarsTable, DriversTable, LapHistoryTable } from '@pitvox/partner-react'
 import '@pitvox/partner-react/styles.css'
 ```
 
-- **`<CompetitionCards>`** — Competition card grid with posters, badges, schedule, and registration status
-- **`<StandingsTable>`** — Championship standings with per-round breakdowns, podium highlights, dropped rounds
-- **`<RoundResults>`** — Round results with session tab bar, driver/car detail, best sector highlighting
-- **`<EntryList>`** — Registered drivers grid with avatars
-- **`<RegisterButton>`** — Register/withdraw toggle (render prop or default button)
+- **`<TracksTable>`** — All tracks with record holders, tag filtering, sorting
+- **`<CarsTable>`** — Cars for a selected track with tag filtering
+- **`<DriversTable>`** — Drivers for a car with sectors (S1/S2/S3), tyre, fuel
+- **`<LapHistoryTable>`** — Driver's lap history with validity and personal best highlighting
 
-You're responsible for wiring up navigation between views and managing state.
+You compose these into your own page layout and wire up navigation between layers. See the [partner templates](https://github.com/meekysoft/pitvox-partner-template) for a complete example using React Router.
 
-### Hooks only
+## Competitions
 
-For fully custom UIs, use the data hooks directly:
+### Hooks
 
 ```jsx
 import {
@@ -187,13 +110,38 @@ import {
 **`useCompetitionAllRounds(competitionId, roundNumbers)`** — Fetch multiple round results in parallel.
 
 **`useCompetitionEntryList(competitionId)`** — Registered drivers.
+
+### Styled components
+
+```jsx
+import {
+  CompetitionCards, StandingsTable, RoundResults, RoundSessionResults,
+  EntryList, RegisterButton, RegistrationPanel,
+} from '@pitvox/partner-react'
+import '@pitvox/partner-react/styles.css'
+```
+
+- **`<CompetitionCards>`** — Card grid with posters, type badges, schedule, registration status
+- **`<StandingsTable>`** — Championship standings with per-round breakdowns, podium highlights
+- **`<RoundResults>`** — Standalone round results (fetches data, renders header + sessions)
+- **`<RoundSessionResults>`** — Session tabs + results table (data-prop driven, no fetch)
+- **`<EntryList>`** — Registered drivers grid with avatars
+- **`<RegisterButton>`** — Register/withdraw toggle (render prop or default button)
+- **`<RegistrationPanel>`** — Registration form + entry list with unregister
+
+### Shared utilities
+
+Useful when composing competition pages:
+
+```jsx
+import { TypeBadge, InfoPill, PODIUM_MEDALS, CompLoadingState, CompEmptyState } from '@pitvox/partner-react'
 ```
 
 ## Driver Dashboard
 
-### Drop-in (recommended)
+### Drop-in composite
 
-One component gives you a complete driver dashboard with profile, stats cards, and current records:
+The `DriverDashboard` is a self-contained component with no routing dependency:
 
 ```jsx
 import { DriverDashboard } from '@pitvox/partner-react'
@@ -210,8 +158,6 @@ function DashboardPage() {
 }
 ```
 
-**Props:**
-
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `steamId` | `string` | — | Driver's Steam ID (required) |
@@ -219,50 +165,84 @@ function DashboardPage() {
 | `memberSince` | `string` | — | ISO date for "Racing since" display |
 | `className` | `string` | — | Additional class on root container |
 
-**Displays:**
-- Driver profile card (avatar, name, racing since)
-- Stats cards: total laps (with track breakdown tooltip), cars used (with car breakdown tooltip), driver rating
-- Current records list sorted by most recent, with track, car, lap time, and game badge
+The dashboard automatically includes:
+- **Upcoming Events** — competition rounds the driver is registered for (CDN-based, always available)
+- **Notifications** — only when `onFetchNotifications` is provided to the provider (see [Notifications](#notifications))
 
 ### Layer components
 
-For more control, use the individual components directly:
+```jsx
+import { DriverProfile, StatsCards, RecordsTable, UpcomingEvents, NotificationsCard } from '@pitvox/partner-react'
+```
+
+- **`<UpcomingEvents>`** — Upcoming competition rounds card (accepts `events` array from `useUpcomingEvents()`)
+- **`<NotificationsCard>`** — Notifications list with read/unread state (accepts `notifications`, `unreadCount`, `onMarkRead`, `onMarkAllRead`)
+
+### Hooks
 
 ```jsx
-import { DriverProfile, StatsCards, RecordsTable } from '@pitvox/partner-react'
-import '@pitvox/partner-react/styles.css'
+import { useDriverStats, useDriverRating, useUpcomingEvents } from '@pitvox/partner-react'
 ```
 
-- **`<DriverProfile>`** — Avatar, driver name, and "Racing since" date
-- **`<StatsCards>`** — Stats cards with icons and hover breakdown tooltips (accepts `stats` from `useDriverStats` and `rating` from `useDriverRating`)
-- **`<RecordsTable>`** — Compact records list sorted by most recent, with expand/collapse
+**`useDriverStats(steamId)`** — Driver stats, records, and ranking from CDN.
+
+**`useDriverRating(steamId)`** — Driver's rating from the partner ratings file.
+
+**`useUpcomingEvents()`** — Upcoming competition rounds the current user is registered for (CDN-based).
 
-### Hooks only
+## Notifications
 
-For fully custom UIs, use the data hooks directly:
+Notifications require a backend to proxy requests to pitvox-api (keeping the API key server-side). Provide callbacks to the provider:
 
 ```jsx
-import { useDriverStats, useDriverRating } from '@pitvox/partner-react'
+<PitVoxPartnerProvider
+  partnerSlug="your-slug"
+  getSteamId={() => user?.steamId ?? null}
+  onFetchNotifications={async (params) => {
+    const res = await fetch(`/api/notifications?limit=${params.limit || 20}`)
+    return res.json() // { notifications: [...], unreadCount: number }
+  }}
+  onMarkNotificationRead={async (id) => {
+    await fetch(`/api/notifications/${id}/read`, { method: 'PATCH' })
+  }}
+  onMarkAllNotificationsRead={async () => {
+    await fetch('/api/notifications/read-all', { method: 'PATCH' })
+  }}
+>
+```
+
+When no callbacks are provided, notification hooks return disabled/empty state and `DriverDashboard` hides the notifications section.
+
+### Hooks
+
+```jsx
+import {
+  useNotifications, useUnreadCount, useMarkNotificationRead,
+  useMarkAllNotificationsRead, useNotificationsEnabled,
+} from '@pitvox/partner-react'
 ```
 
-**`useDriverStats(steamId)`** — Fetch driver stats, records, and ranking from CDN.
-- Shares the same query cache as `useDriverLaps` (same CDN file)
-- Returns `{ data: { driverName, lapCount, trackBreakdown, carBreakdown, recordsHeld, currentRecords, bestRanking, bestRankingTrackId, bestRankingLayout, bestRankingCarId }, isLoading, error }`
+**`useNotifications(options?)`** — Fetch notifications (polls every 30s). Returns `{ data: { notifications, unreadCount }, isLoading }`.
+
+**`useUnreadCount()`** — Unread count for navbar badges. Returns `{ count, isLoading }`.
+
+**`useMarkNotificationRead()`** — Mutation to mark a notification as read.
+
+**`useMarkAllNotificationsRead()`** — Mutation to mark all as read.
 
-**`useDriverRating(steamId)`** — Fetch driver's rating from the partner ratings file.
-- Returns `{ data: { rating, rank, totalDrivers, comboCount, distinctCars, combos }, isLoading, error }`
+**`useNotificationsEnabled()`** — Returns `boolean` — whether notification callbacks are provided.
 
 ## Registration
 
-The SDK supports two registration modes, determined automatically by whether you provide callbacks to the provider.
+The SDK supports two registration modes, determined by whether you provide callbacks to the provider.
 
 ### Basic mode (default)
 
-No configuration needed. The `RegisterButton` and `CompetitionExplorer` render a link to the pitvox.com registration page, where users can sign in with Steam and register.
+No configuration needed. Registration components render links to pitvox.com where users register with Steam.
 
 ### Power mode
 
-For partners with a backend (e.g. an Amplify Lambda that proxies to pitvox-api), provide `onRegister` and `onWithdraw` callbacks to the provider:
+For partners with a backend (e.g. Amplify Lambda proxying to pitvox-api), provide callbacks:
 
 ```jsx
 <PitVoxPartnerProvider
@@ -277,29 +257,21 @@ For partners with a backend (e.g. an Amplify Lambda that proxies to pitvox-api),
 >
 ```
 
-The `RegisterButton` will then render as an in-app button instead of an external link.
-
-### Hooks
+### Registration hooks
 
 ```jsx
-import {
-  useRegistrationStatus,
-  useRegister,
-  useWithdraw,
-  useRegistrationMode,
-  useRegistrationUrl,
-} from '@pitvox/partner-react'
+import { useRegistrationStatus, useRegister, useWithdraw, useRegistrationMode, useRegistrationUrl } from '@pitvox/partner-react'
 ```
 
-**`useRegistrationStatus(competitionId)`** — Check if current user (via `getSteamId`) is registered. Returns `{ data: { isRegistered, entryList } }`.
+**`useRegistrationStatus(competitionId)`** — Check if current user is registered.
 
-**`useRegister(competitionId)`** — Returns a mutation. Delegates to `onRegister` callback. Throws if no callback provided.
+**`useRegister(competitionId)`** — Mutation delegating to `onRegister` callback.
 
-**`useWithdraw(competitionId)`** — Returns a mutation. Delegates to `onWithdraw` callback. Throws if no callback provided.
+**`useWithdraw(competitionId)`** — Mutation delegating to `onWithdraw` callback.
 
-**`useRegistrationMode()`** — Returns `{ isPowerMode, isBasicMode }` based on whether callbacks are provided.
+**`useRegistrationMode()`** — Returns `{ isPowerMode, isBasicMode }`.
 
-**`useRegistrationUrl(competitionId)`** — Returns the pitvox.com registration URL for basic mode.
+**`useRegistrationUrl(competitionId)`** — Returns pitvox.com registration URL for basic mode.
 
 ## Formatting utilities
 
@@ -312,7 +284,8 @@ import {
   formatDate,          // ISO string → "27 Feb 2024"
   formatRelativeTime,  // ISO string → "2h ago"
   formatDelta,         // 542 → "+0.542"
-  formatTyreCompound,  // "SR" → "Soft Race"
+  formatTyreCompound,           // "SR" → "Soft Race"
+  formatNotificationMessage,    // notification → "X beat your record on Track — Car"
 } from '@pitvox/partner-react'
 ```
 
@@ -322,36 +295,25 @@ The default stylesheet uses CSS custom properties. Override them to match your b
 
 ```css
 :root {
-  --pvx-accent: #e11d48;         /* your brand colour */
-  --pvx-bg-card: #1a1a2e;        /* card background */
-  --pvx-sector-best: #22d3ee;    /* best sector highlight */
-  --pvx-rank-gold: #fbbf24;      /* podium colours */
+  --pvx-accent: #e11d48;
+  --pvx-bg-card: #1a1a2e;
+  --pvx-sector-best: #22d3ee;
+  --pvx-rank-gold: #fbbf24;
 }
 ```
 
-All classes are prefixed with `pvx-` to avoid collisions with your existing styles. See `styles.css` for the full list of variables and classes.
+All classes are prefixed with `pvx-` to avoid collisions. See `styles.css` for the full list of variables.
 
-## CDN data paths
+## Partner templates
 
-The SDK reads pre-computed JSON from the PitVox CDN. No API key is needed for read-only leaderboard and competition data.
+For a complete working site using this SDK, see:
 
-| Data | Path |
-|------|------|
-| Leaderboard index | `leaderboards/partners/{slug}/index.json` |
-| Track entries | `leaderboards/partners/{slug}/tracks/{trackId}/{layout}.json` |
-| Driver laps | `laps/partners/{slug}/{userId}.json` |
-| User display names | `users/index.json` |
-| Car metadata | `cars/index.json` |
-| Competition index | `competitions/index.json` |
-| Competition config | `competitions/{slug}/{id}/config.json` |
-| Standings | `competitions/{slug}/{id}/standings.json` |
-| Round results | `competitions/{slug}/{id}/rounds/{n}.json` |
-| Entry list | `competitions/{slug}/{id}/entrylist.json` |
-| Driver ratings | `leaderboards/partners/{slug}/ratings.json` |
+- **[pitvox-partner-template](https://github.com/meekysoft/pitvox-partner-template)** — Basic template (no auth)
+- **[pitvox-partner-template-amplify](https://github.com/meekysoft/pitvox-partner-template-amplify)** — AWS Amplify template with Steam auth and in-app registration
 
-## Local development
+The templates demonstrate how to compose SDK hooks and components into full pages with routing.
 
-To develop against a local version of the SDK:
+## Local development
 
 ```bash
 # In the SDK repo
@@ -367,7 +329,7 @@ Add `resolve.dedupe` to your Vite config to avoid duplicate React instances:
 // vite.config.js
 export default defineConfig({
   resolve: {
-    dedupe: ['react', 'react-dom', 'react-router-dom', '@tanstack/react-query'],
+    dedupe: ['react', 'react-dom', '@tanstack/react-query'],
   },
 })
 ```