From f0d3aa88ef54226d4efecc3e1f65832c72e8e230 Mon Sep 17 00:00:00 2001
From: Jamie B <53781962+JamieB-gu@users.noreply.github.com>
Date: Wed, 10 Dec 2025 14:53:27 +0000
Subject: [PATCH] New football models

A refactoring of our existing football models, to reduce duplication and
allow them to work for upcoming changes to football sportblogs and match
report pages.

These are not currently being used anywhere. The work to have them
replace the existing models, and be used on the aforementioned pages,
will happen in future changes.
---
 dotcom-rendering/src/footballMatchStats.ts | 43 +++++++++++++++
 dotcom-rendering/src/footballMatchV2.ts    | 63 ++++++++++++++++++++++
 dotcom-rendering/src/footballMatchesV2.ts  | 26 +++++++++
 dotcom-rendering/src/footballTeam.ts       |  8 +++
 4 files changed, 140 insertions(+)
 create mode 100644 dotcom-rendering/src/footballMatchStats.ts
 create mode 100644 dotcom-rendering/src/footballMatchV2.ts
 create mode 100644 dotcom-rendering/src/footballMatchesV2.ts
 create mode 100644 dotcom-rendering/src/footballTeam.ts

diff --git a/dotcom-rendering/src/footballMatchStats.ts b/dotcom-rendering/src/footballMatchStats.ts
new file mode 100644
index 00000000000..e892fb3f5ce
--- /dev/null
+++ b/dotcom-rendering/src/footballMatchStats.ts
@@ -0,0 +1,43 @@
+import type { FootballTeam } from './footballTeam';
+
+/**
+ * The stats for each team in a given football match.
+ */
+export type FootballMatchStats = {
+	homeTeam: FootballMatchTeamWithStats;
+	awayTeam: FootballMatchTeamWithStats;
+};
+
+/**
+ * Extended stats information about a given team in a football match, including
+ * a list of players.
+ */
+type FootballMatchTeamWithStats = FootballTeam & {
+	abbreviatedName: string;
+	possession: number;
+	shotsOnTarget: number;
+	shotsOffTarget: number;
+	corners: number;
+	fouls: number;
+	players: FootballPlayer[];
+	statsColour: string;
+};
+
+/**
+ * Information about a player's participation in a given football match.
+ */
+type FootballPlayer = {
+	paID: string;
+	name: string;
+	substitute: boolean;
+	shirtNumber: number;
+	events: PlayerEvent[];
+};
+
+/**
+ * Events involving a particular player in a given football match.
+ */
+type PlayerEvent = {
+	kind: 'substitution' | 'booking' | 'dismissal';
+	minute: number;
+};
diff --git a/dotcom-rendering/src/footballMatchV2.ts b/dotcom-rendering/src/footballMatchV2.ts
new file mode 100644
index 00000000000..b8865d47150
--- /dev/null
+++ b/dotcom-rendering/src/footballMatchV2.ts
@@ -0,0 +1,63 @@
+import type { FootballTeam } from './footballTeam';
+
+/**
+ * There are three states a football match can be in.
+ *
+ * - Before it starts it's known as a "fixture".
+ * - While it's in-play we refer to it as "live".
+ * - Once it's over it's known as a "result".
+ */
+export type FootballMatch = MatchFixture | LiveMatch | MatchResult;
+
+/**
+ * Before a match has started we have some information, such as when it's going
+ * to start and which teams are playing. But we don't have a score or status.
+ */
+export type MatchFixture = MatchData & {
+	kind: 'Fixture';
+	homeTeam: FootballTeam;
+	awayTeam: FootballTeam;
+};
+
+/**
+ * Once a match has started we have additional information beyond what's
+ * available for a {@linkcode MatchFixture}, such as the score.
+ */
+export type LiveMatch = MatchData & {
+	kind: 'Live';
+	homeTeam: FootballMatchTeamWithScore;
+	awayTeam: FootballMatchTeamWithScore;
+	status: string;
+	comment: string | undefined;
+};
+
+/**
+ * When a match is over, we have much the same information as when it's a
+ * {@linkcode LiveMatch}, such as the score. The status is always "full-time"
+ * (FT), so we don't need a property for that.
+ */
+export type MatchResult = MatchData & {
+	kind: 'Result';
+	homeTeam: FootballMatchTeamWithScore;
+	awayTeam: FootballMatchTeamWithScore;
+	comment: string | undefined;
+};
+
+/**
+ * For all football matches we should know what the PA ID is and when it's
+ * scheduled to kick off.
+ */
+type MatchData = {
+	paId: string;
+	kickOff: Date;
+	venue: string;
+};
+
+/**
+ * Once a match has started, we can bundle together information about a team,
+ * such as its name, with its score and which players have scored.
+ */
+type FootballMatchTeamWithScore = FootballTeam & {
+	score: number;
+	scorers: string[];
+};
diff --git a/dotcom-rendering/src/footballMatchesV2.ts b/dotcom-rendering/src/footballMatchesV2.ts
new file mode 100644
index 00000000000..fa1e965df19
--- /dev/null
+++ b/dotcom-rendering/src/footballMatchesV2.ts
@@ -0,0 +1,26 @@
+import type { FootballMatch } from './footballMatchV2';
+
+/**
+ * A collection of football matches happening across one or more days, where
+ * each day is represented by a separate item in the list.
+ */
+export type FootballMatches = FootballCompetitionsOnDay[];
+
+/**
+ * All the football competitions with matches on a given day.
+ */
+type FootballCompetitionsOnDay = {
+	day: Date;
+	competitions: FootballCompetition[];
+};
+
+/**
+ * A selection of football matches happening as part of a given competition.
+ */
+type FootballCompetition = {
+	id: string;
+	tag: string;
+	name: string;
+	nation: string;
+	matches: FootballMatch[];
+};
diff --git a/dotcom-rendering/src/footballTeam.ts b/dotcom-rendering/src/footballTeam.ts
new file mode 100644
index 00000000000..6d08c43589f
--- /dev/null
+++ b/dotcom-rendering/src/footballTeam.ts
@@ -0,0 +1,8 @@
+/**
+ * The basic information we should have about all football teams is their PA ID
+ * and their name.
+ */
+export type FootballTeam = {
+	name: string;
+	paID: string;
+};