From b2b0940bb5b09cbac5dbc6e5a2807ea82c830582 Mon Sep 17 00:00:00 2001
From: Yannick Lyn Fatt <yannick.lynfatt@gmail.com>
Date: Sun, 19 Jul 2026 10:10:33 -0400
Subject: [PATCH 1/2] Rank best Nth-placed teams across groups (World Cup
 style)

Adds the first phase of stage-to-stage advancement: a cross-group
ranking of the teams finishing just below the automatic qualification
spots (e.g. the best third-placed teams), opt-in per stage via
config.best_placed_count.

- BestPlacedCalculator ranks each group's Nth-placed row across groups
  by points, goal difference, then goals for (h2h is meaningless across
  groups, matching FIFA/UEFA cross-group rules)
- Stage page shows the ranking with a qualifying cut-line when enabled
- Create/Edit stage forms gain "Advance per group" and "Best-placed
  qualifiers" fields for grouped formats
- Ranked position derives from advances_count + 1 (default 3rd)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 app/Domain/Standings/BestPlacedCalculator.php |  64 +++++++
 app/Domain/Standings/BestPlacedRow.php        |  31 +++
 app/Http/Controllers/StagesController.php     |  36 +++-
 app/Http/Requests/StoreStageRequest.php       |  19 +-
 app/Http/Requests/UpdateStageRequest.php      |   9 +
 resources/js/components/BestPlacedTable.vue   |  85 +++++++++
 resources/js/pages/Stages/Create.vue          |  21 +++
 resources/js/pages/Stages/Edit.vue            |  24 +++
 resources/js/pages/Stages/Show.vue            |  37 ++++
 tests/Feature/Stages/StageBestPlacedTest.php  | 177 ++++++++++++++++++
 .../Standings/BestPlacedCalculatorTest.php    | 153 +++++++++++++++
 11 files changed, 651 insertions(+), 5 deletions(-)
 create mode 100644 app/Domain/Standings/BestPlacedCalculator.php
 create mode 100644 app/Domain/Standings/BestPlacedRow.php
 create mode 100644 resources/js/components/BestPlacedTable.vue
 create mode 100644 tests/Feature/Stages/StageBestPlacedTest.php
 create mode 100644 tests/Unit/Standings/BestPlacedCalculatorTest.php

diff --git a/app/Domain/Standings/BestPlacedCalculator.php b/app/Domain/Standings/BestPlacedCalculator.php
new file mode 100644
index 0000000..31719b2
--- /dev/null
+++ b/app/Domain/Standings/BestPlacedCalculator.php
@@ -0,0 +1,64 @@
+<?php
+
+namespace App\Domain\Standings;
+
+use App\Models\Group;
+use App\Models\Stage;
+use DomainException;
+use Illuminate\Support\Collection;
+
+/**
+ * Ranks the teams finishing in the same position across every group of a
+ * grouped stage — the "ranking of third-placed teams" table used by World
+ * Cup / Euro style tournaments where the best N of them advance alongside
+ * the automatic qualifiers.
+ *
+ * Each group's table is computed by the stage's regular standings
+ * calculator (so per-group tiebreakers, including head-to-head, still
+ * apply within the group). The cross-group comparison then uses only
+ * points → goal difference → goals for → name: head-to-head is meaningless
+ * across groups because the teams never met, which matches how FIFA and
+ * UEFA rank third-placed teams.
+ *
+ * Groups too small to have a team at the requested position are skipped
+ * rather than erroring, so a lopsided draw (one group of 3, others of 4)
+ * still produces a ranking of the teams that exist.
+ */
+class BestPlacedCalculator
+{
+    public function __construct(private readonly StandingsRegistry $registry)
+    {
+        //
+    }
+
+    /**
+     * @return Collection<int, BestPlacedRow>
+     */
+    public function calculate(Stage $stage, int $position): Collection
+    {
+        if (! $stage->format->hasGroups()) {
+            throw new DomainException(
+                "Stage [{$stage->id}] has format [{$stage->format->value}], which has no groups to rank best-placed teams across."
+            );
+        }
+
+        if ($position < 1) {
+            throw new DomainException("Best-placed position must be at least 1, got [{$position}].");
+        }
+
+        $calculator = $this->registry->for($stage->format);
+
+        return $stage->groups
+            ->map(function (Group $group) use ($stage, $calculator, $position): ?BestPlacedRow {
+                $row = $calculator->calculate($stage, $group)->get($position - 1);
+
+                return $row === null ? null : new BestPlacedRow($group->id, $group->name, $row);
+            })
+            ->filter()
+            ->sort(fn (BestPlacedRow $a, BestPlacedRow $b): int => ($b->row->points <=> $a->row->points)
+                ?: ($b->row->goal_difference <=> $a->row->goal_difference)
+                ?: ($b->row->goals_for <=> $a->row->goals_for)
+                ?: strcasecmp($a->row->team_name, $b->row->team_name))
+            ->values();
+    }
+}
diff --git a/app/Domain/Standings/BestPlacedRow.php b/app/Domain/Standings/BestPlacedRow.php
new file mode 100644
index 0000000..c68f2c7
--- /dev/null
+++ b/app/Domain/Standings/BestPlacedRow.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Domain\Standings;
+
+/**
+ * One row in a cross-group "best Nth-placed teams" ranking — a team's
+ * StandingRow from its own group table, tagged with the group it came from
+ * so the ranking can show (and later seed by) group identity.
+ */
+final readonly class BestPlacedRow
+{
+    public function __construct(
+        public int $group_id,
+        public string $group_name,
+        public StandingRow $row,
+    ) {
+        //
+    }
+
+    /**
+     * @return array<string, int|string>
+     */
+    public function toArray(): array
+    {
+        return [
+            'group_id' => $this->group_id,
+            'group_name' => $this->group_name,
+            ...$this->row->toArray(),
+        ];
+    }
+}
diff --git a/app/Http/Controllers/StagesController.php b/app/Http/Controllers/StagesController.php
index 846a43c..3263b2c 100644
--- a/app/Http/Controllers/StagesController.php
+++ b/app/Http/Controllers/StagesController.php
@@ -3,6 +3,7 @@
 namespace App\Http\Controllers;
 
 use App\Actions\GenerateFixtures;
+use App\Domain\Standings\BestPlacedCalculator;
 use App\Domain\Standings\StandingsRegistry;
 use App\Enums\StageFormat;
 use App\Http\Requests\StoreStageRequest;
@@ -42,7 +43,7 @@ public function store(StoreStageRequest $request, League $league, Season $season
             ->with('status', "Stage \"{$stage->name}\" created.");
     }
 
-    public function show(League $league, Season $season, Stage $stage, StandingsRegistry $standings): Response
+    public function show(League $league, Season $season, Stage $stage, StandingsRegistry $standings, BestPlacedCalculator $bestPlaced): Response
     {
         $this->ensureSeasonInLeague($league, $season);
         $this->ensureStageInSeason($season, $stage);
@@ -63,6 +64,7 @@ public function show(League $league, Season $season, Stage $stage, StandingsRegi
             'season' => $season->only(['id', 'name']),
             'stage' => $stage,
             'standings' => $this->buildStandings($stage, $standings),
+            'bestPlaced' => $this->buildBestPlaced($stage, $bestPlaced),
             'bracket' => $stage->format->isBracket() ? $this->buildBracket($stage) : null,
             'can' => [
                 'update' => request()->user()?->can('update', $stage) ?? false,
@@ -111,6 +113,38 @@ private function buildStandings(Stage $stage, StandingsRegistry $standings): ?ar
         ];
     }
 
+    /**
+     * Cross-group ranking of the teams finishing just below the automatic
+     * qualification spots (position = advances-per-group + 1, so with the
+     * default 2 qualifiers per group this is the third-placed table). Only
+     * built when the stage opts in via config.best_placed_count — the number
+     * of these teams that qualify for the next stage.
+     *
+     * @return null|array{position: int, qualify_count: int, rows: array<int, array<string, mixed>>}
+     */
+    private function buildBestPlaced(Stage $stage, BestPlacedCalculator $calculator): ?array
+    {
+        if (! $stage->format->hasGroups() || $stage->groups->isEmpty()) {
+            return null;
+        }
+
+        $qualifyCount = (int) ($stage->config['best_placed_count'] ?? 0);
+
+        if ($qualifyCount < 1) {
+            return null;
+        }
+
+        $position = ($stage->advances_count ?? 2) + 1;
+
+        return [
+            'position' => $position,
+            'qualify_count' => $qualifyCount,
+            'rows' => $calculator->calculate($stage, $position)
+                ->map(fn ($row) => $row->toArray())
+                ->all(),
+        ];
+    }
+
     /**
      * Shape the knockout games into ordered rounds for the bracket view. Each
      * round carries a human label (Final / Semifinals / …) derived from its
diff --git a/app/Http/Requests/StoreStageRequest.php b/app/Http/Requests/StoreStageRequest.php
index 46db672..c37fae8 100644
--- a/app/Http/Requests/StoreStageRequest.php
+++ b/app/Http/Requests/StoreStageRequest.php
@@ -41,6 +41,7 @@ public function rules(): array
             'advances_count' => ['nullable', 'integer', 'min:1'],
             'config' => ['nullable', 'array'],
             'config.legs_per_group' => ['sometimes', 'integer', 'in:1,2'],
+            'config.best_placed_count' => ['sometimes', 'integer', 'min:1', 'max:16'],
         ];
     }
 
@@ -50,20 +51,28 @@ protected function prepareForValidation(): void
             'order' => $this->input('order', 0),
         ]);
 
-        // Coerce legs_per_group from string to int when it comes from a <Select>
-        // payload, and only keep the key if format is GroupStage (silently
-        // drop it otherwise so it doesn't pollute the JSON column).
+        // Coerce config ints that arrive as strings from form payloads, and
+        // only keep each key when the format supports it (silently drop it
+        // otherwise so it doesn't pollute the JSON column).
         $config = $this->input('config', []);
         if (! is_array($config)) {
             $config = [];
         }
 
-        if (isset($config['legs_per_group']) && $this->input('format') === 'group_stage') {
+        $format = $this->input('format');
+
+        if (isset($config['legs_per_group']) && $format === 'group_stage') {
             $config['legs_per_group'] = (int) $config['legs_per_group'];
         } else {
             unset($config['legs_per_group']);
         }
 
+        if (! empty($config['best_placed_count']) && in_array($format, ['group_stage', 'conference'], true)) {
+            $config['best_placed_count'] = (int) $config['best_placed_count'];
+        } else {
+            unset($config['best_placed_count']);
+        }
+
         $this->merge([
             'config' => empty($config) ? null : $config,
         ]);
@@ -75,6 +84,8 @@ public function messages(): array
             'name.unique' => 'A stage with that name already exists in this season.',
             'ends_on.after_or_equal' => 'End date must be on or after the start date.',
             'config.legs_per_group.in' => 'Legs per group must be either 1 (single round-robin) or 2 (home and away).',
+            'config.best_placed_count.min' => 'Best-placed qualifiers must be at least 1 (leave it blank for none).',
+            'config.best_placed_count.max' => 'Best-placed qualifiers cannot exceed 16.',
         ];
     }
 }
diff --git a/app/Http/Requests/UpdateStageRequest.php b/app/Http/Requests/UpdateStageRequest.php
index 561e050..2da19f5 100644
--- a/app/Http/Requests/UpdateStageRequest.php
+++ b/app/Http/Requests/UpdateStageRequest.php
@@ -43,6 +43,7 @@ public function rules(): array
             'advances_count' => ['nullable', 'integer', 'min:1'],
             'config' => ['nullable', 'array'],
             'config.legs_per_group' => ['sometimes', 'integer', 'in:1,2'],
+            'config.best_placed_count' => ['sometimes', 'integer', 'min:1', 'max:16'],
         ];
     }
 
@@ -62,6 +63,12 @@ protected function prepareForValidation(): void
             unset($config['legs_per_group']);
         }
 
+        if (! empty($config['best_placed_count']) && in_array($format, ['group_stage', 'conference'], true)) {
+            $config['best_placed_count'] = (int) $config['best_placed_count'];
+        } else {
+            unset($config['best_placed_count']);
+        }
+
         $this->merge([
             'config' => empty($config) ? null : $config,
         ]);
@@ -86,6 +93,8 @@ public function messages(): array
             'name.unique' => 'A stage with that name already exists in this season.',
             'ends_on.after_or_equal' => 'End date must be on or after the start date.',
             'config.legs_per_group.in' => 'Legs per group must be either 1 (single round-robin) or 2 (home and away).',
+            'config.best_placed_count.min' => 'Best-placed qualifiers must be at least 1 (leave it blank for none).',
+            'config.best_placed_count.max' => 'Best-placed qualifiers cannot exceed 16.',
         ];
     }
 }
diff --git a/resources/js/components/BestPlacedTable.vue b/resources/js/components/BestPlacedTable.vue
new file mode 100644
index 0000000..1721676
--- /dev/null
+++ b/resources/js/components/BestPlacedTable.vue
@@ -0,0 +1,85 @@
+<script setup lang="ts">
+interface BestPlacedRow {
+    group_id: number;
+    group_name: string;
+    team_id: number;
+    team_name: string;
+    team_acronym: string;
+    played: number;
+    won: number;
+    drawn: number;
+    lost: number;
+    goals_for: number;
+    goals_against: number;
+    goal_difference: number;
+    points: number;
+    form: string;
+}
+
+const props = defineProps<{
+    rows: BestPlacedRow[];
+    qualifyCount: number;
+}>();
+
+function qualifies(index: number): boolean {
+    return index < props.qualifyCount;
+}
+
+function isCutLine(index: number): boolean {
+    return index === props.qualifyCount - 1 && index < props.rows.length - 1;
+}
+</script>
+
+<template>
+    <div class="overflow-hidden rounded-lg border">
+        <table class="w-full text-sm">
+            <thead class="bg-primary text-xs uppercase tracking-wider text-primary-foreground">
+                <tr>
+                    <th class="px-3 py-2 text-right">#</th>
+                    <th class="px-3 py-2 text-left">Team</th>
+                    <th class="px-2 py-2 text-left">Group</th>
+                    <th class="hidden px-2 py-2 text-right tabular-nums sm:table-cell">Pld</th>
+                    <th class="hidden px-2 py-2 text-right tabular-nums md:table-cell">W</th>
+                    <th class="hidden px-2 py-2 text-right tabular-nums md:table-cell">D</th>
+                    <th class="hidden px-2 py-2 text-right tabular-nums md:table-cell">L</th>
+                    <th class="hidden px-2 py-2 text-right tabular-nums lg:table-cell">GF</th>
+                    <th class="hidden px-2 py-2 text-right tabular-nums lg:table-cell">GA</th>
+                    <th class="px-2 py-2 text-right tabular-nums">GD</th>
+                    <th class="px-3 py-2 text-right tabular-nums font-semibold">Pts</th>
+                </tr>
+            </thead>
+            <tbody class="divide-y">
+                <tr
+                    v-for="(row, index) in rows"
+                    :key="row.team_id"
+                    class="border-l-2 hover:bg-muted/30"
+                    :class="[
+                        qualifies(index) ? 'border-l-volt bg-volt/5' : 'border-l-transparent',
+                        isCutLine(index) ? 'border-b-2 border-b-volt/60' : '',
+                    ]"
+                >
+                    <td class="px-3 py-2 text-right font-display text-base tabular-nums" :class="qualifies(index) ? 'font-bold' : 'text-muted-foreground'">
+                        {{ index + 1 }}
+                    </td>
+                    <td class="px-3 py-2">
+                        <span class="mr-2 inline-block w-10 rounded bg-muted px-1 text-center font-display text-xs font-semibold uppercase text-muted-foreground">
+                            {{ row.team_acronym }}
+                        </span>
+                        <span :class="{ 'font-semibold': qualifies(index) }">{{ row.team_name }}</span>
+                    </td>
+                    <td class="px-2 py-2 text-xs text-muted-foreground">{{ row.group_name }}</td>
+                    <td class="hidden px-2 py-2 text-right tabular-nums sm:table-cell">{{ row.played }}</td>
+                    <td class="hidden px-2 py-2 text-right tabular-nums md:table-cell">{{ row.won }}</td>
+                    <td class="hidden px-2 py-2 text-right tabular-nums md:table-cell">{{ row.drawn }}</td>
+                    <td class="hidden px-2 py-2 text-right tabular-nums md:table-cell">{{ row.lost }}</td>
+                    <td class="hidden px-2 py-2 text-right tabular-nums lg:table-cell">{{ row.goals_for }}</td>
+                    <td class="hidden px-2 py-2 text-right tabular-nums lg:table-cell">{{ row.goals_against }}</td>
+                    <td class="px-2 py-2 text-right tabular-nums" :class="{ 'text-emerald-600 dark:text-emerald-400': row.goal_difference > 0, 'text-rose-600 dark:text-rose-400': row.goal_difference < 0 }">
+                        {{ row.goal_difference > 0 ? '+' : '' }}{{ row.goal_difference }}
+                    </td>
+                    <td class="px-3 py-2 text-right font-display text-base font-bold tabular-nums">{{ row.points }}</td>
+                </tr>
+            </tbody>
+        </table>
+    </div>
+</template>
diff --git a/resources/js/pages/Stages/Create.vue b/resources/js/pages/Stages/Create.vue
index 1b089fa..df69c63 100644
--- a/resources/js/pages/Stages/Create.vue
+++ b/resources/js/pages/Stages/Create.vue
@@ -45,6 +45,7 @@ const form = useForm({
     advances_count: null as number | null,
     config: {
         legs_per_group: 1 as 1 | 2,
+        best_placed_count: null as number | null,
     },
 });
 
@@ -129,6 +130,26 @@ function submit() {
                 <InputError :message="form.errors['config.legs_per_group']" />
             </div>
 
+            <div v-if="selectedFormat?.hasGroups" class="grid grid-cols-1 gap-5 sm:grid-cols-2">
+                <div class="grid gap-2">
+                    <Label for="advances_count">Advance per group (optional)</Label>
+                    <Input id="advances_count" type="number" min="1" max="8" v-model="form.advances_count" placeholder="2" />
+                    <p class="text-xs text-muted-foreground">
+                        How many teams from each group qualify automatically. Defaults to 2.
+                    </p>
+                    <InputError :message="form.errors.advances_count" />
+                </div>
+
+                <div class="grid gap-2">
+                    <Label for="best_placed_count">Best-placed qualifiers (optional)</Label>
+                    <Input id="best_placed_count" type="number" min="1" max="16" v-model="form.config.best_placed_count" placeholder="None" />
+                    <p class="text-xs text-muted-foreground">
+                        Extra spots for the best teams finishing just below the cut — e.g. 8 best third-placed teams.
+                    </p>
+                    <InputError :message="form.errors['config.best_placed_count']" />
+                </div>
+            </div>
+
             <div v-if="selectedFormat?.isBracket" class="rounded-md border border-sky-300 bg-sky-50 p-3 text-sm text-sky-900 dark:border-sky-700/40 dark:bg-sky-950/40 dark:text-sky-200">
                 Knockout formats only generate round-1 fixtures up front. Later rounds get populated as winners advance.
             </div>
diff --git a/resources/js/pages/Stages/Edit.vue b/resources/js/pages/Stages/Edit.vue
index 41441d7..a297034 100644
--- a/resources/js/pages/Stages/Edit.vue
+++ b/resources/js/pages/Stages/Edit.vue
@@ -47,6 +47,7 @@ const props = defineProps<{
 }>();
 
 const currentLegs = (props.stage.config?.legs_per_group as 1 | 2 | undefined) ?? 1;
+const currentBestPlaced = (props.stage.config?.best_placed_count as number | undefined) ?? null;
 
 const form = useForm({
     name: props.stage.name,
@@ -56,9 +57,12 @@ const form = useForm({
     advances_count: props.stage.advances_count,
     config: {
         legs_per_group: currentLegs,
+        best_placed_count: currentBestPlaced,
     },
 });
 
+const hasGroupedFormat = ['group_stage', 'conference'].includes(props.stage.format);
+
 const formatLabel = props.formats.find((f) => f.value === props.stage.format)?.label ?? props.stage.format;
 
 const pageBreadcrumbs = computed<BreadcrumbItem[]>(() => [
@@ -139,6 +143,26 @@ function submit() {
                 <InputError :message="form.errors['config.legs_per_group']" />
             </div>
 
+            <div v-if="hasGroupedFormat" class="grid grid-cols-1 gap-5 sm:grid-cols-2">
+                <div class="grid gap-2">
+                    <Label for="advances_count">Advance per group (optional)</Label>
+                    <Input id="advances_count" type="number" min="1" max="8" v-model="form.advances_count" placeholder="2" />
+                    <p class="text-xs text-muted-foreground">
+                        How many teams from each group qualify automatically. Defaults to 2.
+                    </p>
+                    <InputError :message="form.errors.advances_count" />
+                </div>
+
+                <div class="grid gap-2">
+                    <Label for="best_placed_count">Best-placed qualifiers (optional)</Label>
+                    <Input id="best_placed_count" type="number" min="1" max="16" v-model="form.config.best_placed_count" placeholder="None" />
+                    <p class="text-xs text-muted-foreground">
+                        Extra spots for the best teams finishing just below the cut — e.g. 8 best third-placed teams.
+                    </p>
+                    <InputError :message="form.errors['config.best_placed_count']" />
+                </div>
+            </div>
+
             <div class="flex items-center gap-3">
                 <Button type="submit" :disabled="form.processing">Save changes</Button>
                 <Button type="button" variant="ghost" as-child>
diff --git a/resources/js/pages/Stages/Show.vue b/resources/js/pages/Stages/Show.vue
index f2e8e11..2a2faac 100644
--- a/resources/js/pages/Stages/Show.vue
+++ b/resources/js/pages/Stages/Show.vue
@@ -1,6 +1,7 @@
 <script setup lang="ts">
 import { Head, Link, router, useForm } from '@inertiajs/vue3';
 import { computed } from 'vue';
+import BestPlacedTable from '@/components/BestPlacedTable.vue';
 import Bracket from '@/components/Bracket.vue';
 import Breadcrumbs from '@/components/Breadcrumbs.vue';
 import StandingsTable from '@/components/StandingsTable.vue';
@@ -99,6 +100,17 @@ interface GroupedStandingsEntry {
 // (since they're string keys). Vue/TS sees that as Record<string, ...>.
 type Standings = OverallStandings | Record<string, GroupedStandingsEntry> | null;
 
+interface BestPlacedRow extends StandingRow {
+    group_id: number;
+    group_name: string;
+}
+
+interface BestPlaced {
+    position: number;
+    qualify_count: number;
+    rows: BestPlacedRow[];
+}
+
 interface BracketRound {
     round: number;
     label: string;
@@ -119,6 +131,7 @@ const props = defineProps<{
     season: SeasonSummary;
     stage: Stage;
     standings: Standings;
+    bestPlaced: BestPlaced | null;
     bracket: BracketRound[] | null;
     can: {
         update: boolean;
@@ -155,6 +168,15 @@ defineOptions({
     },
 });
 
+/**
+ * 3 → "3rd", 4 → "4th" … for the best-placed card title.
+ */
+function ordinal(n: number): string {
+    const suffix = n % 100 >= 11 && n % 100 <= 13 ? 'th' : (['th', 'st', 'nd', 'rd'][n % 10] ?? 'th');
+
+    return `${n}${suffix}`;
+}
+
 const hasGroupedFormat = computed(() => ['group_stage', 'conference'].includes(props.stage.format));
 const isBracketFormat = computed(() => ['single_elimination', 'double_elimination'].includes(props.stage.format));
 const fixturesGenerated = computed(() => props.stage.games.length > 0);
@@ -308,6 +330,21 @@ function deleteGroup(group: Group) {
             </CardContent>
         </Card>
 
+        <!-- Cross-group ranking of best Nth-placed teams (World Cup / Euro style) -->
+        <Card v-if="bestPlaced && bestPlaced.rows.length > 0">
+            <CardHeader>
+                <CardTitle class="text-base">Ranking of {{ ordinal(bestPlaced.position) }}-placed teams</CardTitle>
+                <CardDescription>
+                    The best {{ bestPlaced.qualify_count }} of these {{ bestPlaced.rows.length }} teams
+                    {{ bestPlaced.qualify_count === 1 ? 'qualifies' : 'qualify' }} alongside the automatic qualifiers.
+                    Ranked across groups by points, goal difference, then goals scored.
+                </CardDescription>
+            </CardHeader>
+            <CardContent>
+                <BestPlacedTable :rows="bestPlaced.rows" :qualify-count="bestPlaced.qualify_count" />
+            </CardContent>
+        </Card>
+
         <!-- Fixture generation card -->
         <Card>
             <CardHeader>
diff --git a/tests/Feature/Stages/StageBestPlacedTest.php b/tests/Feature/Stages/StageBestPlacedTest.php
new file mode 100644
index 0000000..b179e36
--- /dev/null
+++ b/tests/Feature/Stages/StageBestPlacedTest.php
@@ -0,0 +1,177 @@
+<?php
+
+use App\Enums\StageFormat;
+use App\Models\Game;
+use App\Models\Group;
+use App\Models\League;
+use App\Models\Result;
+use App\Models\Season;
+use App\Models\Stage;
+use App\Models\Team;
+
+/**
+ * Build a public-league GroupStage with two groups of three named teams and
+ * a decided set of games so each group has a distinct 3rd place:
+ * "Alpha Third" (3 pts) in Group A and "Beta Third" (0 pts) in Group B.
+ *
+ * @param  array<string, mixed>  $stageAttributes
+ * @return array{0: League, 1: Season, 2: Stage}
+ */
+function bestPlacedStageScaffold(array $stageAttributes = []): array
+{
+    $league = League::factory()->create(['is_public' => true]);
+    $season = Season::factory()->create(['league_id' => $league->id]);
+    $stage = Stage::factory()->groupStage()->create([
+        'season_id' => $season->id,
+        ...$stageAttributes,
+    ]);
+
+    $rosters = [
+        'Group A' => ['Alpha First', 'Alpha Second', 'Alpha Third'],
+        'Group B' => ['Beta First', 'Beta Second', 'Beta Third'],
+    ];
+
+    $teams = [];
+    foreach ($rosters as $groupName => $teamNames) {
+        $group = Group::factory()->create(['stage_id' => $stage->id, 'name' => $groupName]);
+
+        foreach ($teamNames as $teamName) {
+            $team = Team::factory()->create(['name' => $teamName]);
+            $season->teams()->attach($team);
+            $group->teams()->attach($team);
+            $teams[$teamName] = ['team' => $team, 'group' => $group];
+        }
+    }
+
+    $play = function (string $home, string $away, int $hs, int $as) use ($stage, $teams): void {
+        $game = Game::factory()->create([
+            'stage_id' => $stage->id,
+            'season_id' => $stage->season_id,
+            'group_id' => $teams[$home]['group']->id,
+            'home_team_id' => $teams[$home]['team']->id,
+            'away_team_id' => $teams[$away]['team']->id,
+            'match_date' => now()->subDay(),
+        ]);
+
+        Result::factory()->create([
+            'game_id' => $game->id,
+            'home_team_score' => $hs,
+            'away_team_score' => $as,
+        ]);
+    };
+
+    // Group A: First 6 pts, Second 3 pts (h2h over Third), Third 3 pts.
+    $play('Alpha First', 'Alpha Second', 1, 0);
+    $play('Alpha First', 'Alpha Third', 2, 0);
+    $play('Alpha Third', 'Alpha Second', 1, 0);
+    $play('Alpha Second', 'Alpha Third', 2, 0);
+
+    // Group B: First 6 pts, Second 3 pts, Third 0 pts.
+    $play('Beta First', 'Beta Second', 1, 0);
+    $play('Beta First', 'Beta Third', 2, 0);
+    $play('Beta Second', 'Beta Third', 1, 0);
+
+    return [$league, $season, $stage];
+}
+
+describe('Stage show bestPlaced prop', function () {
+    it('ranks best third-placed teams across groups when best_placed_count is configured', function () {
+        [$league, $season, $stage] = bestPlacedStageScaffold([
+            'config' => ['best_placed_count' => 1],
+        ]);
+
+        $this->get("/leagues/{$league->slug}/seasons/{$season->id}/stages/{$stage->id}")
+            ->assertSuccessful()
+            ->assertInertia(fn ($page) => $page
+                ->where('bestPlaced.position', 3)
+                ->where('bestPlaced.qualify_count', 1)
+                ->has('bestPlaced.rows', 2)
+                ->where('bestPlaced.rows.0.team_name', 'Alpha Third')
+                ->where('bestPlaced.rows.0.group_name', 'Group A')
+                ->where('bestPlaced.rows.0.points', 3)
+                ->where('bestPlaced.rows.1.team_name', 'Beta Third')
+                ->where('bestPlaced.rows.1.points', 0)
+            );
+    });
+
+    it('derives the ranked position from advances_count', function () {
+        [$league, $season, $stage] = bestPlacedStageScaffold([
+            'advances_count' => 1,
+            'config' => ['best_placed_count' => 1],
+        ]);
+
+        $this->get("/leagues/{$league->slug}/seasons/{$season->id}/stages/{$stage->id}")
+            ->assertSuccessful()
+            ->assertInertia(fn ($page) => $page
+                ->where('bestPlaced.position', 2)
+                ->where('bestPlaced.rows.0.team_name', 'Alpha Second')
+            );
+    });
+
+    it('omits the ranking when best_placed_count is not configured', function () {
+        [$league, $season, $stage] = bestPlacedStageScaffold();
+
+        $this->get("/leagues/{$league->slug}/seasons/{$season->id}/stages/{$stage->id}")
+            ->assertSuccessful()
+            ->assertInertia(fn ($page) => $page->where('bestPlaced', null));
+    });
+});
+
+describe('Stage config.best_placed_count validation', function () {
+    it('accepts best_placed_count for a group stage', function () {
+        $league = League::factory()->create();
+        $season = Season::factory()->create(['league_id' => $league->id]);
+
+        $this->actingAs($league->owner)
+            ->post("/leagues/{$league->slug}/seasons/{$season->id}/stages", [
+                'name' => 'Group Stage',
+                'format' => StageFormat::GroupStage->value,
+                'config' => ['best_placed_count' => '8'],
+            ])
+            ->assertRedirect();
+
+        expect(Stage::where('name', 'Group Stage')->firstOrFail()->config)
+            ->toBe(['best_placed_count' => 8]);
+    });
+
+    it('silently drops best_placed_count for ungrouped formats', function () {
+        $league = League::factory()->create();
+        $season = Season::factory()->create(['league_id' => $league->id]);
+
+        $this->actingAs($league->owner)
+            ->post("/leagues/{$league->slug}/seasons/{$season->id}/stages", [
+                'name' => 'Regular Season',
+                'format' => StageFormat::RoundRobinSingle->value,
+                'config' => ['best_placed_count' => 4],
+            ])
+            ->assertRedirect();
+
+        expect(Stage::where('name', 'Regular Season')->firstOrFail()->config)->toBeNull();
+    });
+
+    it('rejects a best_placed_count above 16', function () {
+        $league = League::factory()->create();
+        $season = Season::factory()->create(['league_id' => $league->id]);
+
+        $this->actingAs($league->owner)
+            ->post("/leagues/{$league->slug}/seasons/{$season->id}/stages", [
+                'name' => 'Group Stage',
+                'format' => StageFormat::GroupStage->value,
+                'config' => ['best_placed_count' => 17],
+            ])
+            ->assertSessionHasErrors('config.best_placed_count');
+    });
+
+    it('updates best_placed_count on an existing group stage', function () {
+        [$league, $season, $stage] = bestPlacedStageScaffold();
+
+        $this->actingAs($league->owner)
+            ->put("/leagues/{$league->slug}/seasons/{$season->id}/stages/{$stage->id}", [
+                'name' => $stage->name,
+                'config' => ['best_placed_count' => 4],
+            ])
+            ->assertRedirect();
+
+        expect($stage->fresh()->config['best_placed_count'])->toBe(4);
+    });
+});
diff --git a/tests/Unit/Standings/BestPlacedCalculatorTest.php b/tests/Unit/Standings/BestPlacedCalculatorTest.php
new file mode 100644
index 0000000..667f63d
--- /dev/null
+++ b/tests/Unit/Standings/BestPlacedCalculatorTest.php
@@ -0,0 +1,153 @@
+<?php
+
+use App\Domain\Standings\BestPlacedCalculator;
+use App\Models\Game;
+use App\Models\Group;
+use App\Models\Result;
+use App\Models\Season;
+use App\Models\Stage;
+use App\Models\Team;
+
+/**
+ * Build a GroupStage with named groups of named teams, e.g.
+ * ['Group A' => ['Ajax', 'Barca', 'Celtic'], 'Group B' => [...]].
+ * Returns [stage, teams keyed by name, groups keyed by name].
+ *
+ * @param  array<string, array<int, string>>  $groupMap
+ * @return array{0: Stage, 1: array<string, Team>, 2: array<string, Group>}
+ */
+function bestPlacedScaffold(array $groupMap): array
+{
+    $season = Season::factory()->create();
+    $stage = Stage::factory()->groupStage()->create(['season_id' => $season->id]);
+
+    $teams = [];
+    $groups = [];
+
+    foreach ($groupMap as $groupName => $teamNames) {
+        $group = Group::factory()->create(['stage_id' => $stage->id, 'name' => $groupName]);
+        $groups[$groupName] = $group;
+
+        foreach ($teamNames as $teamName) {
+            $team = Team::factory()->create(['name' => $teamName]);
+            $season->teams()->attach($team);
+            $group->teams()->attach($team);
+            $teams[$teamName] = $team;
+        }
+    }
+
+    return [$stage, $teams, $groups];
+}
+
+/**
+ * Persist a decided group game between two named teams.
+ */
+function decideGroupGame(Stage $stage, Group $group, Team $home, Team $away, int $hs, int $as): void
+{
+    $game = Game::factory()->create([
+        'stage_id' => $stage->id,
+        'season_id' => $stage->season_id,
+        'group_id' => $group->id,
+        'home_team_id' => $home->id,
+        'away_team_id' => $away->id,
+        'match_date' => now()->subDay(),
+    ]);
+
+    Result::factory()->create([
+        'game_id' => $game->id,
+        'home_team_score' => $hs,
+        'away_team_score' => $as,
+    ]);
+}
+
+function freshForBestPlaced(Stage $stage): Stage
+{
+    return $stage->fresh(['groups.teams', 'games.result', 'season.teams']);
+}
+
+describe('BestPlacedCalculator', function () {
+    it('ranks third-placed teams across groups by points, then goal difference, then goals for', function () {
+        [$stage, $t, $g] = bestPlacedScaffold([
+            'Group A' => ['A1', 'A2', 'A3'],
+            'Group B' => ['B1', 'B2', 'B3'],
+            'Group C' => ['C1', 'C2', 'C3'],
+        ]);
+
+        // Group A: A3 finishes 3rd with 3 pts, GD −4 (h2h vs A3 puts A2 2nd).
+        decideGroupGame($stage, $g['Group A'], $t['A1'], $t['A2'], 1, 0);
+        decideGroupGame($stage, $g['Group A'], $t['A1'], $t['A3'], 3, 0);
+        decideGroupGame($stage, $g['Group A'], $t['A3'], $t['A2'], 2, 0);
+        decideGroupGame($stage, $g['Group A'], $t['A2'], $t['A3'], 3, 0);
+
+        // Group B: B3 finishes 3rd with 0 pts.
+        decideGroupGame($stage, $g['Group B'], $t['B1'], $t['B3'], 2, 0);
+        decideGroupGame($stage, $g['Group B'], $t['B2'], $t['B3'], 1, 0);
+        decideGroupGame($stage, $g['Group B'], $t['B1'], $t['B2'], 1, 0);
+
+        // Group C: C3 finishes 3rd with 3 pts, GD −2 (h2h vs C3 puts C2 2nd)
+        // — better GD than A3, so C3 outranks A3 across groups.
+        decideGroupGame($stage, $g['Group C'], $t['C1'], $t['C2'], 1, 0);
+        decideGroupGame($stage, $g['Group C'], $t['C1'], $t['C3'], 1, 0);
+        decideGroupGame($stage, $g['Group C'], $t['C3'], $t['C2'], 1, 0);
+        decideGroupGame($stage, $g['Group C'], $t['C2'], $t['C3'], 2, 0);
+
+        $ranked = app(BestPlacedCalculator::class)->calculate(freshForBestPlaced($stage), 3);
+
+        expect($ranked)->toHaveCount(3);
+        expect($ranked[0]->row->team_name)->toBe('C3'); // 3 pts, GD −2
+        expect($ranked[0]->group_name)->toBe('Group C');
+        expect($ranked[1]->row->team_name)->toBe('A3'); // 3 pts, GD −4
+        expect($ranked[2]->row->team_name)->toBe('B3'); // 0 pts
+    });
+
+    it('skips groups that have no team at the requested position', function () {
+        [$stage, $t, $g] = bestPlacedScaffold([
+            'Group A' => ['A1', 'A2', 'A3'],
+            'Group B' => ['B1', 'B2'], // only two teams — no 3rd place
+        ]);
+
+        $ranked = app(BestPlacedCalculator::class)->calculate(freshForBestPlaced($stage), 3);
+
+        expect($ranked)->toHaveCount(1);
+        expect($ranked[0]->group_name)->toBe('Group A');
+    });
+
+    it('breaks full ties alphabetically for a stable order', function () {
+        // Group tables share the name tiebreak, so with no games played each
+        // group's 3rd place is its alphabetically-last team.
+        [$stage, $t, $g] = bestPlacedScaffold([
+            'Group A' => ['Zebra FC', 'A1', 'A2'],
+            'Group B' => ['Bete FC', 'B1', 'B2'],
+        ]);
+
+        $ranked = app(BestPlacedCalculator::class)->calculate(freshForBestPlaced($stage), 3);
+
+        expect($ranked->map(fn ($r) => $r->row->team_name)->all())
+            ->toBe(['Bete FC', 'Zebra FC']);
+    });
+
+    it('tags each row with the group it came from and serializes both', function () {
+        [$stage, $t, $g] = bestPlacedScaffold([
+            'Group A' => ['A1', 'A2', 'A3'],
+        ]);
+
+        $ranked = app(BestPlacedCalculator::class)->calculate(freshForBestPlaced($stage), 3);
+
+        expect($ranked[0]->group_id)->toBe($g['Group A']->id);
+        expect($ranked[0]->toArray())
+            ->toHaveKeys(['group_id', 'group_name', 'team_id', 'team_name', 'points', 'goal_difference']);
+    });
+
+    it('rejects ungrouped formats', function () {
+        $season = Season::factory()->create();
+        $stage = Stage::factory()->create(['season_id' => $season->id]);
+
+        app(BestPlacedCalculator::class)->calculate($stage, 3);
+    })->throws(DomainException::class);
+
+    it('rejects positions below 1', function () {
+        [$stage] = bestPlacedScaffold(['Group A' => ['A1', 'A2']]);
+
+        app(BestPlacedCalculator::class)->calculate(freshForBestPlaced($stage), 0);
+    })->throws(DomainException::class);
+});

From 80cbf8b52997ce595c2c1123e162174da1f4f4ce Mon Sep 17 00:00:00 2001
From: Yannick Lyn Fatt <yannick.lynfatt@gmail.com>
Date: Sun, 19 Jul 2026 10:23:23 -0400
Subject: [PATCH 2/2] Highlight qualification zones in group standings tables

The best-placed ranking card sits below all the group tables, so an
admin enabling it saw no visible change in the standings themselves.
Group tables now draw World Cup style qualification zones:

- top advances_count rows (automatic qualifiers): volt highlight
- the best-placed candidate row: amber highlight
- zones only appear when the stage sets advances_count, so tables
  without a qualification cut keep the plain leader highlight

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 resources/js/components/StandingsTable.vue   | 53 +++++++++++++++++---
 resources/js/pages/Stages/Show.vue           | 19 ++++++-
 tests/Feature/Stages/StageBestPlacedTest.php | 14 ++++++
 3 files changed, 78 insertions(+), 8 deletions(-)

diff --git a/resources/js/components/StandingsTable.vue b/resources/js/components/StandingsTable.vue
index d196738..c0c82aa 100644
--- a/resources/js/components/StandingsTable.vue
+++ b/resources/js/components/StandingsTable.vue
@@ -14,9 +14,50 @@ interface StandingRow {
     form: string;
 }
 
-defineProps<{
-    rows: StandingRow[];
-}>();
+/**
+ * Optional qualification zones (World Cup style group tables):
+ *   - qualifyCount: top N rows qualify automatically → volt highlight.
+ *   - bestPlacedPosition: the row at this 1-based position might qualify as a
+ *     best-placed team → amber highlight (only used when qualifyCount is set).
+ * When qualifyCount is absent the table falls back to highlighting the leader.
+ */
+const props = withDefaults(
+    defineProps<{
+        rows: StandingRow[];
+        qualifyCount?: number | null;
+        bestPlacedPosition?: number | null;
+    }>(),
+    { qualifyCount: null, bestPlacedPosition: null },
+);
+
+type RowZone = 'qualify' | 'best-placed' | null;
+
+function rowZone(index: number): RowZone {
+    if (props.qualifyCount === null) {
+        return index === 0 ? 'qualify' : null;
+    }
+
+    if (index < props.qualifyCount) {
+        return 'qualify';
+    }
+
+    if (props.bestPlacedPosition !== null && index === props.bestPlacedPosition - 1) {
+        return 'best-placed';
+    }
+
+    return null;
+}
+
+function rowClasses(index: number): string {
+    switch (rowZone(index)) {
+        case 'qualify':
+            return 'border-l-volt bg-volt/5';
+        case 'best-placed':
+            return 'border-l-amber-400 bg-amber-400/10';
+        default:
+            return 'border-l-transparent';
+    }
+}
 
 function formColor(letter: string): string {
     switch (letter) {
@@ -55,16 +96,16 @@ function formColor(letter: string): string {
                     v-for="(row, index) in rows"
                     :key="row.team_id"
                     class="border-l-2 hover:bg-muted/30"
-                    :class="index === 0 ? 'border-l-volt bg-volt/5' : 'border-l-transparent'"
+                    :class="rowClasses(index)"
                 >
-                    <td class="px-3 py-2 text-right font-display text-base tabular-nums" :class="index === 0 ? 'font-bold' : 'text-muted-foreground'">
+                    <td class="px-3 py-2 text-right font-display text-base tabular-nums" :class="rowZone(index) === 'qualify' ? 'font-bold' : 'text-muted-foreground'">
                         {{ index + 1 }}
                     </td>
                     <td class="px-3 py-2">
                         <span class="mr-2 inline-block w-10 rounded bg-muted px-1 text-center font-display text-xs font-semibold uppercase text-muted-foreground">
                             {{ row.team_acronym }}
                         </span>
-                        <span :class="{ 'font-semibold': index === 0 }">{{ row.team_name }}</span>
+                        <span :class="{ 'font-semibold': rowZone(index) === 'qualify' }">{{ row.team_name }}</span>
                     </td>
                     <td class="hidden px-2 py-2 text-right tabular-nums sm:table-cell">{{ row.played }}</td>
                     <td class="hidden px-2 py-2 text-right tabular-nums md:table-cell">{{ row.won }}</td>
diff --git a/resources/js/pages/Stages/Show.vue b/resources/js/pages/Stages/Show.vue
index 2a2faac..226796d 100644
--- a/resources/js/pages/Stages/Show.vue
+++ b/resources/js/pages/Stages/Show.vue
@@ -67,6 +67,7 @@ interface Stage {
     order: number;
     starts_on: string | null;
     ends_on: string | null;
+    advances_count: number | null;
     config: Record<string, unknown> | null;
     groups: Group[];
     games: Game[];
@@ -178,6 +179,14 @@ function ordinal(n: number): string {
 }
 
 const hasGroupedFormat = computed(() => ['group_stage', 'conference'].includes(props.stage.format));
+
+/**
+ * Qualification zones for the group tables. Only drawn when the stage says
+ * how many advance per group — otherwise the tables keep the plain leader
+ * highlight and don't imply a qualification cut that doesn't exist.
+ */
+const groupQualifyCount = computed<number | null>(() => props.stage.advances_count);
+const groupBestPlacedPosition = computed<number | null>(() => props.bestPlaced?.position ?? null);
 const isBracketFormat = computed(() => ['single_elimination', 'double_elimination'].includes(props.stage.format));
 const fixturesGenerated = computed(() => props.stage.games.length > 0);
 
@@ -318,14 +327,20 @@ function deleteGroup(group: Group) {
         <Card v-if="groupedStandings">
             <CardHeader>
                 <CardTitle class="text-base">Standings</CardTitle>
-                <CardDescription>One table per group.</CardDescription>
+                <CardDescription>
+                    <template v-if="groupQualifyCount">
+                        Top {{ groupQualifyCount }} in each group qualify automatically<template v-if="groupBestPlacedPosition">;
+                        <span class="text-amber-600 dark:text-amber-400">amber</span> rows can still advance as best-placed teams (ranked below)</template>.
+                    </template>
+                    <template v-else>One table per group.</template>
+                </CardDescription>
             </CardHeader>
             <CardContent class="flex flex-col gap-6">
                 <section v-for="entry in groupedStandings" :key="entry.group.id" class="flex flex-col gap-2">
                     <h3 class="text-sm font-semibold tracking-wide text-muted-foreground">
                         {{ entry.group.name }}
                     </h3>
-                    <StandingsTable :rows="entry.rows" />
+                    <StandingsTable :rows="entry.rows" :qualify-count="groupQualifyCount" :best-placed-position="groupBestPlacedPosition" />
                 </section>
             </CardContent>
         </Card>
diff --git a/tests/Feature/Stages/StageBestPlacedTest.php b/tests/Feature/Stages/StageBestPlacedTest.php
index b179e36..aab0849 100644
--- a/tests/Feature/Stages/StageBestPlacedTest.php
+++ b/tests/Feature/Stages/StageBestPlacedTest.php
@@ -94,6 +94,20 @@ function bestPlacedStageScaffold(array $stageAttributes = []): array
             );
     });
 
+    it('exposes advances_count so the group tables can draw qualification zones', function () {
+        [$league, $season, $stage] = bestPlacedStageScaffold([
+            'advances_count' => 2,
+            'config' => ['best_placed_count' => 1],
+        ]);
+
+        $this->get("/leagues/{$league->slug}/seasons/{$season->id}/stages/{$stage->id}")
+            ->assertSuccessful()
+            ->assertInertia(fn ($page) => $page
+                ->where('stage.advances_count', 2)
+                ->where('bestPlaced.position', 3)
+            );
+    });
+
     it('derives the ranked position from advances_count', function () {
         [$league, $season, $stage] = bestPlacedStageScaffold([
             'advances_count' => 1,