guardian · mxdvl · Oct 5, 2023 · Oct 2, 2023 · Oct 5, 2023 · cemms1
diff --git a/dotcom-rendering/docs/lightbox.md b/dotcom-rendering/docs/lightbox.md
@@ -31,7 +31,7 @@ Frontend's lightbox was added to the Guardian's website in 2014. [The PR to add
 
 ## How it gets hydrated
 
-On the server, we only insert a small amount of html and zero javascript. This html can be found in LightboxLayout. On the client hydration is trigged when the page url contains a hash that martches an expected pattern, namely, `img-[n]`. Using the `deferUntil='hash'` feature of Islands, we only execute the Lightbox javascript at the point the url changes and lightbox is requested.
+On the server, we only insert a small amount of html and zero javascript. This html can be found in LightboxLayout. On the client hydration is trigged when the page url contains a hash that martches an expected pattern, namely, `img-[n]`. Using the `defer={{ until: 'hash' }}` feature of Islands, we only execute the Lightbox javascript at the point the url changes and lightbox is requested.
 
 ## How it works
 
@@ -45,7 +45,7 @@ You open and close the lightbox by changing the url. When a reader clicks the 'c
 
 This file is used on the server to co er each article image with an <a> tag. No javascript is used here, only platform features and css.
 
-If the image is clicked the a tag captured this and mutates the url to add a hash in the form `img-[n]`. This triggers hydration based on the `deferUntil='hash'` island.
+If the image is clicked the a tag captured this and mutates the url to add a hash in the form `img-[n]`. This triggers hydration based on the `defer={{ until: 'hash' }}` island.
 
 ### `LightboxLayout`
 

@@ -514,19 +514,7 @@ declare namespace JSX {
 		'amp-youtube': any;
 
 		/** Island {@link ./src/components/Island.tsx} */
-		'gu-island': {
-			name: string;
-			deferUntil?: 'idle' | 'visible' | 'interaction' | 'hash';
-			rootMargin?: string;
-			clientOnly?: boolean;
-			props: any;
-			children: React.ReactNode;
-			/**
-			 * This should be a stringified JSON of `ConfigContext`
-			 * @see /dotcom-rendering/src/types/configContext.ts
-			 */
-			config: string;
-		};
+		'gu-island': import('./src/components/Island.tsx').GuIsland;
 	}
 
 	interface IntrinsicAttributes {

diff --git a/dotcom-rendering/src/components/AllEditorialNewslettersPage.tsx b/dotcom-rendering/src/components/AllEditorialNewslettersPage.tsx
@@ -45,13 +45,13 @@ export const AllEditorialNewslettersPage = ({
 			/>
 			<SkipTo id="maincontent" label="Skip to main content" />
 			<SkipTo id="navigation" label="Skip to navigation" />
-			<Island clientOnly={true} deferUntil="idle">
+			<Island clientOnly={true} defer={{ until: 'idle' }}>
 				<AlreadyVisited />
 			</Island>
-			<Island clientOnly={true} deferUntil="idle">
+			<Island clientOnly={true} defer={{ until: 'idle' }}>
 				<FocusStyles />
 			</Island>
-			<Island clientOnly={true} deferUntil="idle">
+			<Island clientOnly={true} defer={{ until: 'idle' }}>
 				<Metrics
 					commercialMetricsEnabled={
 						!!newslettersPage.config.switches.commercialMetrics

diff --git a/dotcom-rendering/src/components/ArticleBody.tsx b/dotcom-rendering/src/components/ArticleBody.tsx
@@ -218,7 +218,7 @@ export const ArticleBody = ({
 				dir={languageDirection}
 			>
 				{isRecipe(tags) && (
-					<Island deferUntil="hash" clientOnly={true}>
+					<Island defer={{ until: 'hash' }} clientOnly={true}>
 						<RecipeMultiplier />
 					</Island>
 				)}

diff --git a/dotcom-rendering/src/components/ArticleLastUpdated.tsx b/dotcom-rendering/src/components/ArticleLastUpdated.tsx
@@ -32,7 +32,7 @@ export const ArticleLastUpdated = ({ format, lastUpdated }: Props) => {
 		<div css={lastUpdatedStyles(palette)}>
 			{format.design === ArticleDesign.LiveBlog && (
 				<span css={livePulseIconStyles(palette)}>
-					<Island deferUntil="visible">
+					<Island defer={{ until: 'visible' }}>
 						<PulsingDot />
 					</Island>
 					LIVE

diff --git a/dotcom-rendering/src/components/ArticleMeta.tsx b/dotcom-rendering/src/components/ArticleMeta.tsx
@@ -334,7 +334,7 @@ export const ArticleMeta = ({
 		>
 			<div css={meta(format)}>
 				{branding && (
-					<Island deferUntil="visible">
+					<Island defer={{ until: 'visible' }}>
 						<Branding
 							branding={branding}
 							palette={palette}
@@ -380,7 +380,7 @@ export const ArticleMeta = ({
 							)}
 							{messageUs &&
 								format.design === ArticleDesign.LiveBlog && (
-									<Island deferUntil="visible">
+									<Island defer={{ until: 'visible' }}>
 										<SendAMessage
 											formFields={messageUs.formFields}
 											formId={messageUs.formId}
@@ -449,7 +449,10 @@ export const ArticleMeta = ({
 						>
 							<div>
 								{isCommentable && (
-									<Island clientOnly={true} deferUntil="idle">
+									<Island
+										clientOnly={true}
+										defer={{ until: 'idle' }}
+									>
 										<CommentCount
 											discussionApiUrl={discussionApiUrl}
 											shortUrlId={shortUrlId}

diff --git a/dotcom-rendering/src/components/ArticlePage.tsx b/dotcom-rendering/src/components/ArticlePage.tsx
@@ -78,15 +78,15 @@ export const ArticlePage = (props: WebProps | AppProps) => {
 					<Island clientOnly={true}>
 						<LightboxHash />
 					</Island>
-					<Island clientOnly={true} deferUntil="hash">
+					<Island clientOnly={true} defer={{ until: 'hash' }}>
 						<LightboxJavascript
 							format={format}
 							images={article.imagesForLightbox}
 						/>
 					</Island>
 				</>
 			)}
-			<Island clientOnly={true} deferUntil="idle">
+			<Island clientOnly={true} defer={{ until: 'idle' }}>
 				<FocusStyles />
 			</Island>
 			{(format.design === ArticleDesign.LiveBlog ||
@@ -96,20 +96,20 @@ export const ArticlePage = (props: WebProps | AppProps) => {
 			{renderingTarget === 'Web' && (
 				<>
 					<SkipTo id="navigation" label="Skip to navigation" />
-					<Island clientOnly={true} deferUntil="idle">
+					<Island clientOnly={true} defer={{ until: 'idle' }}>
 						<AlreadyVisited />
 					</Island>
-					<Island clientOnly={true} deferUntil="idle">
+					<Island clientOnly={true} defer={{ until: 'idle' }}>
 						<Metrics
 							commercialMetricsEnabled={
 								!!article.config.switches.commercialMetrics
 							}
 						/>
 					</Island>
-					<Island clientOnly={true} deferUntil="idle">
+					<Island clientOnly={true} defer={{ until: 'idle' }}>
 						<BrazeMessaging idApiUrl={article.config.idApiUrl} />
 					</Island>
-					<Island clientOnly={true} deferUntil="idle">
+					<Island clientOnly={true} defer={{ until: 'idle' }}>
 						<ReaderRevenueDev
 							shouldHideReaderRevenue={
 								article.shouldHideReaderRevenue

diff --git a/dotcom-rendering/src/components/Card/Card.tsx b/dotcom-rendering/src/components/Card/Card.tsx
@@ -350,7 +350,7 @@ export const Card = ({
 								min-height: 10px;
 							`}
 						>
-							<Island deferUntil="visible">
+							<Island defer={{ until: 'visible' }}>
 								<CardCommentCount
 									format={format}
 									discussionApiUrl={discussionApiUrl}

diff --git a/dotcom-rendering/src/components/DiscussionLayout.tsx b/dotcom-rendering/src/components/DiscussionLayout.tsx
@@ -44,7 +44,7 @@ export const DiscussionLayout = ({
 				// If we're not hiding an advert stretch to the right
 				stretchRight={!hideAd}
 				leftContent={
-					<Island clientOnly={true} deferUntil="visible">
+					<Island clientOnly={true} defer={{ until: 'visible' }}>
 						<DiscussionMeta
 							format={format}
 							discussionApiUrl={discussionApiUrl}
@@ -69,7 +69,7 @@ export const DiscussionLayout = ({
 							max-width: 100%;
 						`}
 					>
-						<Island deferUntil="visible">
+						<Island defer={{ until: 'visible' }}>
 							<DiscussionContainer
 								format={format}
 								discussionApiUrl={discussionApiUrl}

diff --git a/dotcom-rendering/src/components/EmailSignUpSwitcher.tsx b/dotcom-rendering/src/components/EmailSignUpSwitcher.tsx
@@ -19,7 +19,7 @@ export const EmailSignUpSwitcher = ({
 	const { renderingTarget } = useConfig();
 
 	return renderingTarget === 'Apps' ? (
-		<Island clientOnly={true} deferUntil="idle">
+		<Island clientOnly={true} defer={{ until: 'idle' }}>
 			<AppEmailSignUp skipToIndex={index} {...emailSignUpProps} />
 		</Island>
 	) : (

diff --git a/dotcom-rendering/src/components/Footer.tsx b/dotcom-rendering/src/components/Footer.tsx
@@ -272,7 +272,7 @@ const FooterLinks = ({
 
 	const rrLinks = (
 		<div css={readerRevenueLinks}>
-			<Island deferUntil="visible" clientOnly={true}>
+			<Island defer={{ until: 'visible' }} clientOnly={true}>
 				<ReaderRevenueLinks
 					urls={urls}
 					editionId={editionId}

diff --git a/dotcom-rendering/src/components/FrontMostViewed.tsx b/dotcom-rendering/src/components/FrontMostViewed.tsx
@@ -72,7 +72,7 @@ export const FrontMostViewed = ({
 		>
 			{/* We only need hydration if there are multiple tabs */}
 			{showMostViewedTab ? (
-				<Island deferUntil="visible">
+				<Island defer={{ until: 'visible' }}>
 					<MostViewedFooter
 						tabs={tabs}
 						sectionId="Most viewed"

diff --git a/dotcom-rendering/src/components/FrontPage.tsx b/dotcom-rendering/src/components/FrontPage.tsx
@@ -57,13 +57,13 @@ export const FrontPage = ({ front, NAV }: Props) => {
 			/>
 			<SkipTo id="maincontent" label="Skip to main content" />
 			<SkipTo id="navigation" label="Skip to navigation" />
-			<Island clientOnly={true} deferUntil="idle">
+			<Island clientOnly={true} defer={{ until: 'idle' }}>
 				<AlreadyVisited />
 			</Island>
-			<Island clientOnly={true} deferUntil="idle">
+			<Island clientOnly={true} defer={{ until: 'idle' }}>
 				<FocusStyles />
 			</Island>
-			<Island clientOnly={true} deferUntil="idle">
+			<Island clientOnly={true} defer={{ until: 'idle' }}>
 				<Metrics
 					commercialMetricsEnabled={
 						!!front.config.switches.commercialMetrics
@@ -83,10 +83,10 @@ export const FrontPage = ({ front, NAV }: Props) => {
 			<Island clientOnly={true}>
 				<SetAdTargeting adTargeting={adTargeting} />
 			</Island>
-			<Island clientOnly={true} deferUntil="idle">
+			<Island clientOnly={true} defer={{ until: 'idle' }}>
 				<BrazeMessaging idApiUrl={front.config.idApiUrl} />
 			</Island>
-			<Island clientOnly={true} deferUntil="idle">
+			<Island clientOnly={true} defer={{ until: 'idle' }}>
 				<ReaderRevenueDev shouldHideReaderRevenue={false} />
 			</Island>
 			<FrontLayout front={front} NAV={NAV} />

diff --git a/dotcom-rendering/src/components/FrontSection.tsx b/dotcom-rendering/src/components/FrontSection.tsx
@@ -697,13 +697,13 @@ export const FrontSection = ({
 			>
 				{isString(targetedTerritory) &&
 				isAustralianTerritory(targetedTerritory) ? (
-					<Island deferUntil="visible">
+					<Island defer={{ until: 'visible' }}>
 						<AustralianTerritorySwitcher
 							targetedTerritory={targetedTerritory}
 						/>
 					</Island>
 				) : showMore ? (
-					<Island deferUntil="interaction">
+					<Island defer={{ until: 'interaction' }}>
 						<ShowMore
 							title={title}
 							sectionId={sectionId}

diff --git a/dotcom-rendering/src/components/GroupedNewsletterList.tsx b/dotcom-rendering/src/components/GroupedNewsletterList.tsx
@@ -13,7 +13,7 @@ export const GroupedNewslettersList = ({ groupedNewsletters }: Props) => {
 		<>
 			{groupedNewsletters.groups.map((group, index) => (
 				<Section fullWidth={true} key={group.title}>
-					<Island deferUntil="idle">
+					<Island defer={{ until: 'idle' }}>
 						<CarouselForNewsletters
 							heading={group.title}
 							onwardsSource="newsletters-page"

diff --git a/dotcom-rendering/src/components/Header.tsx b/dotcom-rendering/src/components/Header.tsx
@@ -73,11 +73,11 @@ export const Header = ({
 		</Island>
 
 		<div css={[hasPageSkin ? pageSkinContainer : center, explicitHeight]}>
-			<Island deferUntil="hash" clientOnly={true}>
+			<Island defer={{ until: 'hash' }} clientOnly={true}>
 				<Snow />
 			</Island>
 			<Logo editionId={editionId} hasPageSkin={hasPageSkin} />
-			<Island deferUntil="idle" clientOnly={true}>
+			<Island defer={{ until: 'idle' }} clientOnly={true}>
 				<SupportTheG
 					urls={urls}
 					editionId={editionId}

diff --git a/dotcom-rendering/src/components/Island.test.tsx b/dotcom-rendering/src/components/Island.test.tsx
@@ -0,0 +1,39 @@
+/**
+ * @file
+ * Test that impossible prop combinations are caught by TypeScript.
+ *
+ * What we're really testing is that this file compiles.
+ *
+ * The tests themselves are not really testing anything, but because it's a
+ * *.test.tsx, Jest will run it.
+ *
+ * The test are just there to stop Jest blowing up when it gets the compiled version.
+ */
+
+import { Island } from './Island';
+
+const Mock = () => <>🏝️</>;
+
+() => (
+	<Island>
+		<Mock />
+	</Island>
+);
+
+() => (
+	<Island defer={{ until: 'interaction' }}>
+		<Mock />
+	</Island>
+);
+
+() => (
+	// @ts-expect-error -- until interaction must have
+	// server-rendered fallback
+	<Island defer={{ until: 'interaction' }} clientOnly={true}>
+		<Mock />
+	</Island>
+);
+
+// this is just to stop Jest complaining about no tests
+test('this is not a real test, ignore it, it tells you nothing useful 💃', () =>
+	undefined);