Move and rename TagPage types (#13372)

JamieB-gu · web-flow · commit 7d6fa8e79498 · 2025-02-17T16:11:45.000Z
The purpose of this change is to refactor and simplify the codebase,
making it clearer which types and files relate to the data that comes
from frontend. A new `frontend` directory has been created to contain
frontend types and their corresponding schemas. Currently these are
distributed across the codebase and it can be difficult to follow their
usage. The first files to be moved into this directory are
`feTagPage.ts`, a new file to hold the `FETagPage` type, and
`feTagPage.json`, the existing tag page JSON schema file. The other
frontend types and schemas will follow in later changes, as moving them
all together would constitute a very large diff.

This change also renames `FETagPageType` to `FETagPage` and
`DCRTagPageType` to `TagPage`. Removal of the `DCR` prefix has occurred
for two reasons. Firstly, the project is now called DCAR. Secondly,
we're in DCAR (previously DCR), so we can assume all types without a
prefix belong to this project. By contrast, any type that's derived from
frontend remains prefixed with `FE` to differentiate it. The `Type`
suffix has been removed because it's not necessary to suffix a type with
the word `Type`, and this convention was applied inconsistently, so
removing it reduces noise in the codebase.

`FrontPagination` has also been renamed to `TagPagePagination`. Tag
pages are paginated but fronts are not, and this was already partially
reflected by the fact this type was defined in `tagPage.ts` rather than
`front.ts`.
diff --git a/.prettierignore b/.prettierignore
@@ -5,6 +5,7 @@ pnpm-lock.yaml
 
 # generated files
 dotcom-rendering/src/model/*-schema.json
+dotcom-rendering/src/frontend/schemas
 dotcom-rendering/stories/generated
 
 # specific files
diff --git a/dotcom-rendering/scripts/jsonSchema/schema.mjs b/dotcom-rendering/scripts/jsonSchema/schema.mjs
@@ -11,7 +11,7 @@ const program = TJS.getProgramFromFiles(
 	[
 		path.resolve(`${root}/index.d.ts`),
 		path.resolve(`${root}/src/types/frontend.ts`),
-		path.resolve(`${root}/src/types/tagPage.ts`),
+		path.resolve(`${root}/src/frontend/feTagPage.ts`),
 		path.resolve(`${root}/src/types/newslettersPage.ts`),
 		path.resolve(`${root}/src/types/editionsCrossword.ts`),
 		path.resolve(`${root}/src/feFootballDataPage.ts`),
@@ -42,8 +42,8 @@ const schemas = [
 		file: `${root}/src/model/front-schema.json`,
 	},
 	{
-		typeName: 'FETagPageType',
-		file: `${root}/src/model/tag-page-schema.json`,
+		typeName: 'FETagPage',
+		file: `${root}/src/frontend/schemas/feTagPage.json`,
 	},
 	{
 		typeName: 'FENewslettersPageType',
diff --git a/dotcom-rendering/src/components/FrontSection.tsx b/dotcom-rendering/src/components/FrontSection.tsx
@@ -11,7 +11,7 @@ import type {
 	DCRContainerPalette,
 	TreatType,
 } from '../types/front';
-import type { DCRFrontPagination } from '../types/tagPage';
+import type { TagPagePagination } from '../types/tagPage';
 import { isAustralianTerritory, type Territory } from '../types/territory';
 import { AustralianTerritorySwitcher } from './AustralianTerritorySwitcher.importable';
 import { ContainerOverrides } from './ContainerOverrides';
@@ -74,7 +74,7 @@ type Props = {
 	ajaxUrl?: string;
 	/** Puts pagination at the bottom of the container allowing the user to navigate to other pages,
 	 * usually used on the last container on a page */
-	pagination?: DCRFrontPagination;
+	pagination?: TagPagePagination;
 	/** Does this front section reside on a "paid for" content front */
 	isOnPaidContentFront?: boolean;
 	/** Indicates if the container is targetted to a specific territory */
diff --git a/dotcom-rendering/src/components/TagPage.tsx b/dotcom-rendering/src/components/TagPage.tsx
@@ -6,7 +6,7 @@ import { ArticleDesign, ArticleDisplay, Pillar } from '../lib/articleFormat';
 import { rootStyles } from '../lib/rootStyles';
 import { filterABTestSwitches } from '../model/enhance-switches';
 import type { NavType } from '../model/extract-nav';
-import type { DCRTagPageType } from '../types/tagPage';
+import type { TagPage as TagPageModel } from '../types/tagPage';
 import { AlreadyVisited } from './AlreadyVisited.importable';
 import { useConfig } from './ConfigContext';
 import { DarkModeMessage } from './DarkModeMessage';
@@ -18,7 +18,7 @@ import { SetAdTargeting } from './SetAdTargeting.importable';
 import { SkipTo } from './SkipTo';
 
 type Props = {
-	tagPage: DCRTagPageType;
+	tagPage: TagPageModel;
 	NAV: NavType;
 };
 
diff --git a/dotcom-rendering/src/frontend/README.md b/dotcom-rendering/src/frontend/README.md
@@ -0,0 +1,3 @@
+# The `frontend` Directory
+
+This contains code related to the requests sent to DCAR from frontend. In practice this means the TypeScript types representing JSON data sent via POST request to DCAR, and the JSON schema files that are generated from them by `scripts/jsonSchema`.
diff --git a/dotcom-rendering/src/frontend/feTagPage.ts b/dotcom-rendering/src/frontend/feTagPage.ts
@@ -0,0 +1,28 @@
+import type { EditionId } from '../lib/edition';
+import type { CommercialProperties } from '../types/commercial';
+import type { FooterType } from '../types/footer';
+import type { FEFrontCard, FEFrontConfigType } from '../types/front';
+import type { FENavType } from '../types/frontend';
+import type { FEPagination, FETagType } from '../types/tag';
+
+export type FETagPage = {
+	contents: FEFrontCard[];
+	pagination?: FEPagination;
+	nav: FENavType;
+	tags: {
+		tags: FETagType[];
+	};
+	editionId: EditionId;
+	editionLongForm: string;
+	guardianBaseURL: string;
+	pageId: string;
+	webTitle: string;
+	webURL: string;
+	config: FEFrontConfigType;
+	commercialProperties: CommercialProperties;
+	pageFooter: FooterType;
+	isAdFreeUser: boolean;
+	forceDay: boolean;
+	canonicalUrl?: string;
+	contributionsServiceUrl: string;
+};
diff --git a/dotcom-rendering/src/frontend/schemas/feTagPage.json b/dotcom-rendering/src/frontend/schemas/feTagPage.json
diff --git a/dotcom-rendering/src/layouts/TagPageLayout.tsx b/dotcom-rendering/src/layouts/TagPageLayout.tsx
@@ -26,11 +26,11 @@ import {
 } from '../lib/getTagPageAdPositions';
 import { enhanceTags } from '../model/enhanceTags';
 import type { NavType } from '../model/extract-nav';
-import type { DCRTagPageType } from '../types/tagPage';
+import type { TagPage as TagPageModel } from '../types/tagPage';
 import { BannerWrapper, Stuck } from './lib/stickiness';
 
 interface Props {
-	tagPage: DCRTagPageType;
+	tagPage: TagPageModel;
 	NAV: NavType;
 }
 
diff --git a/dotcom-rendering/src/lib/canRenderAds.ts b/dotcom-rendering/src/lib/canRenderAds.ts
@@ -1,14 +1,14 @@
 import type { ArticleDeprecated } from '../types/article';
 import type { DCRFrontType } from '../types/front';
 import type { RenderingTarget } from '../types/renderingTarget';
-import type { DCRTagPageType } from '../types/tagPage';
+import type { TagPage } from '../types/tagPage';
 
 /**
  * Checks the page for a number of conditions that should
  * prevent ads from being displayed.
  */
 export const canRenderAds = (
-	pageData: ArticleDeprecated | DCRFrontType | DCRTagPageType,
+	pageData: ArticleDeprecated | DCRFrontType | TagPage,
 	renderingTarget?: RenderingTarget,
 ): boolean => {
 	if (renderingTarget === 'Apps') {
diff --git a/dotcom-rendering/src/lib/contributions.ts b/dotcom-rendering/src/lib/contributions.ts
@@ -11,7 +11,7 @@ import { userBenefitsDataIsUpToDate } from '../client/userFeatures/cookies/userB
 import type { ArticleDeprecated } from '../types/article';
 import type { DCRFrontType } from '../types/front';
 import type { DCRNewslettersPageType } from '../types/newslettersPage';
-import type { DCRTagPageType } from '../types/tagPage';
+import type { TagPage } from '../types/tagPage';
 
 // User Attributes API cookies (created on sign-in)
 export const RECURRING_CONTRIBUTOR_COOKIE = 'gu_recurring_contributor';
@@ -195,11 +195,7 @@ export const recentlyClosedBanner = (
 };
 
 export const getContributionsServiceUrl = (
-	config:
-		| ArticleDeprecated
-		| DCRFrontType
-		| DCRTagPageType
-		| DCRNewslettersPageType,
+	config: ArticleDeprecated | DCRFrontType | TagPage | DCRNewslettersPageType,
 ): string => process.env.SDC_URL ?? config.contributionsServiceUrl;
 
 type PurchaseInfo = HeaderPayload['targeting']['purchaseInfo'];
diff --git a/dotcom-rendering/src/model/validate.ts b/dotcom-rendering/src/model/validate.ts
@@ -3,17 +3,17 @@ import type { Options } from 'ajv';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import type { FEFrontType } from '../../src/types/front';
+import type { FETagPage } from '../frontend/feTagPage';
+import tagPageSchema from '../frontend/schemas/feTagPage.json';
 import type { Block } from '../types/blocks';
 import type { FEEditionsCrosswords } from '../types/editionsCrossword';
 import type { FEArticleType } from '../types/frontend';
 import type { FENewslettersPageType } from '../types/newslettersPage';
-import type { FETagPageType } from '../types/tagPage';
 import articleSchema from './article-schema.json';
 import blockSchema from './block-schema.json';
 import editionsCrosswordSchema from './editions-crossword-schema.json';
 import frontSchema from './front-schema.json';
 import newslettersPageSchema from './newsletter-page-schema.json';
-import tagPageSchema from './tag-page-schema.json';
 
 const options: Options = {
 	verbose: false,
@@ -27,7 +27,7 @@ addFormats(ajv);
 
 const validateArticle = ajv.compile<FEArticleType>(articleSchema);
 const validateFront = ajv.compile<FEFrontType>(frontSchema);
-const validateTagPage = ajv.compile<FETagPageType>(tagPageSchema);
+const validateTagPage = ajv.compile<FETagPage>(tagPageSchema);
 const validateAllEditorialNewslettersPage = ajv.compile<FENewslettersPageType>(
 	newslettersPageSchema,
 );
@@ -72,7 +72,7 @@ export const validateAsFrontType = (data: unknown): FEFrontType => {
 	);
 };
 
-export const validateAsTagPageType = (data: unknown): FETagPageType => {
+export const validateAsFETagPage = (data: unknown): FETagPage => {
 	if (validateTagPage(data)) return data;
 
 	const url =
diff --git a/dotcom-rendering/src/server/handler.front.web.ts b/dotcom-rendering/src/server/handler.front.web.ts
@@ -1,5 +1,6 @@
 import { isUndefined } from '@guardian/libs';
 import type { RequestHandler } from 'express';
+import type { FETagPage } from '../frontend/feTagPage';
 import { decideTagPageBranding, pickBrandingForEdition } from '../lib/branding';
 import { decideTrail } from '../lib/decideTrail';
 import { enhanceCards } from '../model/enhanceCards';
@@ -10,10 +11,10 @@ import {
 } from '../model/extractTrendingTopics';
 import { groupTrailsByDates } from '../model/groupTrailsByDates';
 import { getSpeedFromTrails } from '../model/slowOrFastByTrails';
-import { validateAsFrontType, validateAsTagPageType } from '../model/validate';
+import { validateAsFETagPage, validateAsFrontType } from '../model/validate';
 import type { DCRFrontType, FEFrontType } from '../types/front';
 import type { FETagType } from '../types/tag';
-import type { DCRTagPageType, FETagPageType } from '../types/tagPage';
+import type { TagPage } from '../types/tagPage';
 import { makePrefetchHeader } from './lib/header';
 import { recordTypeAndPlatform } from './lib/logging-store';
 import { renderFront, renderTagPage } from './render.front.web';
@@ -53,7 +54,7 @@ const enhanceFront = (body: unknown): DCRFrontType => {
 	};
 };
 
-const tagPageWebTitle = (tagPage: FETagPageType) => {
+const tagPageWebTitle = (tagPage: FETagPage) => {
 	const { pagination } = tagPage;
 	if (!isUndefined(pagination) && pagination.currentPage > 1) {
 		return `${tagPage.webTitle} | Page ${pagination.currentPage} of ${pagination.lastPage} | The Guardian`;
@@ -76,8 +77,8 @@ export const getBadgeUrl = (tag: FETagType): string | undefined => {
 	return `https://sport.guim.co.uk/football/crests/120/${teamId}.png`;
 };
 
-const enhanceTagPage = (body: unknown): DCRTagPageType => {
-	const data: FETagPageType = validateAsTagPageType(body);
+const enhanceTagPage = (body: unknown): TagPage => {
+	const data: FETagPage = validateAsFETagPage(body);
 
 	const enhancedCards = enhanceCards(data.contents, {
 		cardInTagPage: true,
diff --git a/dotcom-rendering/src/server/render.front.web.tsx b/dotcom-rendering/src/server/render.front.web.tsx
@@ -17,7 +17,7 @@ import { extractNAV } from '../model/extract-nav';
 import { createGuardian } from '../model/guardian';
 import type { Config } from '../types/configContext';
 import type { DCRFrontType } from '../types/front';
-import type { DCRTagPageType } from '../types/tagPage';
+import type { TagPage as TagPageModel } from '../types/tagPage';
 import { htmlPageTemplate } from './htmlPageTemplate';
 
 interface Props {
@@ -179,7 +179,7 @@ export const renderFront = ({
 export const renderTagPage = ({
 	tagPage,
 }: {
-	tagPage: DCRTagPageType;
+	tagPage: TagPageModel;
 }): { html: string; prefetchScripts: string[] } => {
 	const title = tagPage.webTitle;
 	const NAV = extractNAV(tagPage.nav);
diff --git a/dotcom-rendering/src/types/tagPage.ts b/dotcom-rendering/src/types/tagPage.ts
@@ -3,31 +3,9 @@ import type { Tuple } from '../lib/tuple';
 import type { CollectionBranding } from './branding';
 import type { CommercialProperties } from './commercial';
 import type { FooterType } from './footer';
-import type { DCRFrontCard, FEFrontCard, FEFrontConfigType } from './front';
+import type { DCRFrontCard, FEFrontConfigType } from './front';
 import type { FENavType } from './frontend';
-import type { FEPagination, FETagType } from './tag';
-
-export interface FETagPageType {
-	contents: FEFrontCard[];
-	pagination?: FEPagination;
-	nav: FENavType;
-	tags: {
-		tags: FETagType[];
-	};
-	editionId: EditionId;
-	editionLongForm: string;
-	guardianBaseURL: string;
-	pageId: string;
-	webTitle: string;
-	webURL: string;
-	config: FEFrontConfigType;
-	commercialProperties: CommercialProperties;
-	pageFooter: FooterType;
-	isAdFreeUser: boolean;
-	forceDay: boolean;
-	canonicalUrl?: string;
-	contributionsServiceUrl: string;
-}
+import type { FETagType } from './tag';
 
 /**
  * Represents a set of trails grouped by their year, month & optionally day of publication.
@@ -55,7 +33,7 @@ export interface GroupedTrailsSlowMpu extends GroupedTrailsBase {
 	trails: Tuple<DCRFrontCard, 2 | 4 | 5 | 7>;
 }
 
-export interface DCRTagPageType {
+export interface TagPage {
 	groupedTrails: Array<
 		GroupedTrails | GroupedTrailsFastMpu | GroupedTrailsSlowMpu
 	>;
@@ -73,7 +51,7 @@ export interface DCRTagPageType {
 	isAdFreeUser: boolean;
 	trendingTopics?: FETagType[];
 	speed: 'slow' | 'fast';
-	pagination?: DCRFrontPagination;
+	pagination?: TagPagePagination;
 	header: {
 		title: string;
 		description?: string;
@@ -84,7 +62,7 @@ export interface DCRTagPageType {
 	contributionsServiceUrl: string;
 }
 
-export interface DCRFrontPagination {
+export interface TagPagePagination {
 	pageId: string;
 	sectionName: string;
 	currentPage: number;

Original file line number	Diff line number	Diff line change
`@@ -11,7 +11,7 @@ const program = TJS.getProgramFromFiles(`
`11`	`11`	`[`
`12`	`12`	path.resolve(`${root}/index.d.ts`),
`13`	`13`	path.resolve(`${root}/src/types/frontend.ts`),
`14`		- path.resolve(`${root}/src/types/tagPage.ts`),
	`14`	+ path.resolve(`${root}/src/frontend/feTagPage.ts`),
`15`	`15`	path.resolve(`${root}/src/types/newslettersPage.ts`),
`16`	`16`	path.resolve(`${root}/src/types/editionsCrossword.ts`),
`17`	`17`	path.resolve(`${root}/src/feFootballDataPage.ts`),
`@@ -42,8 +42,8 @@ const schemas = [`
`42`	`42`	file: `${root}/src/model/front-schema.json`,
`43`	`43`	`},`
`44`	`44`	`{`
`45`		`- typeName: 'FETagPageType',`
`46`		- file: `${root}/src/model/tag-page-schema.json`,
	`45`	`+ typeName: 'FETagPage',`
	`46`	+ file: `${root}/src/frontend/schemas/feTagPage.json`,
`47`	`47`	`},`
`48`	`48`	`{`
`49`	`49`	`typeName: 'FENewslettersPageType',`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	+# The `frontend` Directory
	`2`	`+`
	`3`	+This contains code related to the requests sent to DCAR from frontend. In practice this means the TypeScript types representing JSON data sent via POST request to DCAR, and the JSON schema files that are generated from them by `scripts/jsonSchema`.