New football models (#14995)

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.

Author: JamieB-gu

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;
+};

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[];
+};

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[];
+};

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;
+};