Support nested islands 🏝️ (#14205)

* Use context to track depth of nested islands

* Change context to an object

* Wrap hydrated components in `IslandProvider` to set context

* Remove debug output

* Rename config key

* Add tests for Island context

* Update test description

Author: jamesmockett

dotcom-rendering/src/client/islands/doHydration.tsx

@@ -5,6 +5,7 @@ import { isUndefined, log, startPerformanceMeasure } from '@guardian/libs';
 import { createElement } from 'react';
 import { hydrateRoot } from 'react-dom/client';
 import { ConfigProvider } from '../../components/ConfigContext';
+import { IslandProvider } from '../../components/IslandContext';
 import type { Config } from '../../types/configContext';
 
 declare global {
@@ -61,7 +62,11 @@ export const doHydration = async (
 				element,
 				<ConfigProvider value={config}>
 					<CacheProvider value={emotionCache}>
-						{createElement(module[name], data)}
+						{/* Child islands should not be hydrated separately */}
+						<IslandProvider value={{ isChild: true }}>
+							{/* The component to hydrate must be a single JSX Element */}
+							{createElement(module[name], data)}
+						</IslandProvider>
 					</CacheProvider>
 				</ConfigProvider>,
 			);

dotcom-rendering/src/components/Island.tsx

@@ -1,4 +1,6 @@
+import { useContext } from 'react';
 import type { ScheduleOptions, SchedulePriority } from '../lib/scheduler';
+import { IslandContext, IslandProvider } from './IslandContext';
 
 type DeferredProps = {
 	visible: {
@@ -55,17 +57,29 @@ export const Island = ({ priority, defer, children, role }: IslandProps) => {
 	// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access -- Type definitions on children are limited
 	const name = String(children.type.name);
 
+	/**
+	 * Context tracks whether current island is a child of another
+	 */
+	const island = useContext(IslandContext);
+
 	return (
-		<gu-island
-			name={name}
-			priority={priority}
-			deferUntil={defer?.until}
-			props={JSON.stringify(children.props)}
-			rootMargin={rootMargin}
-			data-spacefinder-role={role}
-		>
-			{children}
-		</gu-island>
+		<IslandProvider value={{ isChild: true }}>
+			{/* Child islands defer to nearest parent island for hydration */}
+			{island.isChild ? (
+				children
+			) : (
+				<gu-island
+					name={name}
+					priority={priority}
+					deferUntil={defer?.until}
+					props={JSON.stringify(children.props)}
+					rootMargin={rootMargin}
+					data-spacefinder-role={role}
+				>
+					{children}
+				</gu-island>
+			)}
+		</IslandProvider>
 	);
 };
 

dotcom-rendering/src/components/IslandContext.test.tsx

@@ -0,0 +1,68 @@
+import { render } from '@testing-library/react';
+import { Island } from './Island';
+
+describe('IslandContext tracks nesting of islands', () => {
+	test('Single island', () => {
+		const { container } = render(
+			<Island priority="feature" defer={{ until: 'visible' }}>
+				<span>🏝️</span>
+			</Island>,
+		);
+		const islands = container.querySelectorAll('gu-island');
+		expect(islands.length).toBe(1);
+	});
+
+	test('Nested island', () => {
+		const { container } = render(
+			<Island priority="feature" defer={{ until: 'visible' }}>
+				<div>
+					<Island priority="feature" defer={{ until: 'visible' }}>
+						<span>🏝️</span>
+					</Island>
+				</div>
+			</Island>,
+		);
+		const islands = container.querySelectorAll('gu-island');
+		expect(islands.length).toBe(1);
+	});
+
+	test('Multiple nested islands', () => {
+		const { container } = render(
+			<Island priority="critical">
+				<div>
+					<Island priority="critical">
+						<div>
+							<Island priority="critical">
+								<span>🏝️</span>
+							</Island>
+							<Island priority="critical">
+								<span>🏝️</span>
+							</Island>
+						</div>
+					</Island>
+				</div>
+			</Island>,
+		);
+		const islands = container.querySelectorAll('gu-island');
+		expect(islands.length).toBe(1);
+	});
+
+	test('Parent island includes props for child islands', () => {
+		const { container } = render(
+			<Island priority="feature" defer={{ until: 'visible' }}>
+				<div>
+					<Island priority="feature" defer={{ until: 'visible' }}>
+						<span className="archipelago">🏝️</span>
+					</Island>
+				</div>
+			</Island>,
+		);
+		const island = container.querySelector('gu-island');
+		expect(island).toHaveAttribute(
+			'props',
+			expect.stringContaining(
+				'"props":{"className":"archipelago","children":"🏝️"}',
+			),
+		);
+	});
+});

dotcom-rendering/src/components/IslandContext.tsx

@@ -0,0 +1,19 @@
+import { createContext } from 'react';
+
+type Config = {
+	isChild: boolean;
+};
+
+/**
+ * Context to track whether the current island is a child of another island.
+ * Child islands defer to the nearest parent island for hydration.
+ */
+export const IslandContext = createContext<Config>({ isChild: false });
+
+export const IslandProvider = ({
+	value,
+	children,
+}: {
+	value: Config;
+	children: React.ReactNode;
+}) => <IslandContext.Provider value={value}>{children}</IslandContext.Provider>;