docs(islands): less repetition & more descriptions

- automatically infer the title from the component name
- add more descriptions about why some of the components
need to be islands

dotcom-rendering/scripts/islands/island-descriptions.mjs

@@ -112,10 +112,11 @@ const getIslands = async (report) => {
 				: '';
 
 			const description =
-				matched?.[1]
+				`# ${name.replaceAll(/([A-Z])/g, ' $1')}\n` +
+				(matched?.[1]
 					?.split('\n')
 					.map((jsdoc_line) => jsdoc_line.slice(3))
-					.join('\n') ?? `# ${name} \n No description yet… 😢`;
+					.join('\n') ?? `No description yet… 😢`);
 
 			const html = await processor.process(description);
 

dotcom-rendering/src/components/AlreadyVisited.importable.tsx

@@ -2,11 +2,15 @@ import { useEffect } from 'react';
 import { incrementAlreadyVisited } from '../lib/alreadyVisited';
 
 /**
- * # AlreadyVisited
- *
  * Increment the already visited count.
  *
- * @returns {} _No visual or DOM output_
+ * ## Why does this need to be an Island?
+ *
+ * This modifies local storage values.
+ *
+ * ---
+ *
+ * Does not render **anything**.
  */
 export const AlreadyVisited = () => {
 	useEffect(() => {

dotcom-rendering/src/components/AudioAtomWrapper.importable.tsx

@@ -19,8 +19,14 @@ type Props = {
 };
 
 /**
- * # AudioAtomWrapper
+ * ## Why does this need to be an Island?
  *
+ * The audio atom is interactive.
+ * Requires consent to use audio ads.
+ *
+ * ---
+ *
+ * (No visual story exists)
  */
 export const AudioAtomWrapper = ({
 	id,

dotcom-rendering/src/components/AustralianTerritorySwitcher.importable.tsx

@@ -40,6 +40,19 @@ const labelStyles = css`
 type Props = {
 	targetedTerritory: AustralianTerritory;
 };
+
+/**
+ * Allows containers targetted to a specific territory to be changed
+ * to a different territory. E.g New South Wales to Victoria
+ *
+ * ## Why does this need to be an Island?
+ *
+ * We use cookies to set the user’s territory.
+ *
+ * ---
+ *
+ * [`AustralianTerritorySwitcher` on Chromatic](https://www.chromatic.com/component?appId=63e251470cfbe61776b0ef19&csfId=components-australianterritoryswitcher--victoria&buildNumber=2967)
+ */
 export const AustralianTerritorySwitcher = ({ targetedTerritory }: Props) => {
 	const [expanded, setExpanded] = useState(false);
 

dotcom-rendering/src/components/Branding.importable.tsx

@@ -163,8 +163,6 @@ type Props = {
 };
 
 /**
- * # Branding
- *
  * Wrapper around the logo and link for sponsored or paid for content.
  *
  * ## Why does this need to be an Island?

dotcom-rendering/src/components/BrazeMessaging.importable.tsx

@@ -8,6 +8,14 @@ type Props = {
 /**
  * This component ensures we call buildBrazeMessaging at least once
  * on every page
+ *
+ * ## Why does this need to be an Island?
+ *
+ * All behaviour is client-side.
+ *
+ * ---
+ *
+ * Does not render **anything**.
  */
 export const BrazeMessaging = ({ idApiUrl }: Props) => {
 	const { brazeMessages, brazeCards } = useBraze(idApiUrl);

dotcom-rendering/src/components/CalloutBlockComponent.importable.tsx

@@ -11,8 +11,6 @@ const collapsibleCalloutStyle = css`
 `;
 
 /**
- * # Callout Block Component
- *
  * A callout to readers to share their stories.
  * This is the updated version of the CalloutEmbedBlockComponent.
  *

dotcom-rendering/src/components/CalloutEmbedBlockComponent.importable.tsx

@@ -130,8 +130,6 @@ let hasFormBeenOpened = true;
 type FormDataType = { [key in string]: unknown };
 
 /**
- * # Callout Embed Block Component
- *
  * A callout to readers to share their stories.
  *
  * ## Why does this need to be an Island?

dotcom-rendering/src/components/Carousel.importable.tsx

@@ -843,8 +843,6 @@ const decideCarouselColours = (
 };
 
 /**
- * # Carousel
- *
  * A carousel of cards, mainly used in onward journeys,
  * at the bottom of articles
  *

dotcom-rendering/src/components/CommentCount.importable.tsx

@@ -72,12 +72,15 @@ const linkStyles = css`
 `;
 
 /**
- * # CommentCount
- *
  * Shows the number of comments at the top of an article.
+ *
+ * ## Why does this need to be an Island?
+ *
  * Fetches the count from the discussion API.
  *
- * [Storybook `Count`](https://637e40d1bc73bf3f604394b9-rzazjyrwhc.chromatic.com/?path=/story/components-counts)
+ * ---
+ *
+ * [`Count` on Chromatic](https://www.chromatic.com/component?appId=63e251470cfbe61776b0ef19&csfId=components-counts&buildNumber=2967)
  */
 export const CommentCount = ({
 	discussionApiUrl,

dotcom-rendering/src/components/DiscussionContainer.importable.tsx

@@ -4,22 +4,27 @@ import { Discussion } from './Discussion';
 import { DiscussionWhenSignedIn } from './DiscussionWhenSignedIn';
 
 /**
- * DiscussionContainer
- *
  * A wrapper component that decides if the user is signed in or not.
  *
- * If they
- * are, it renders DiscussionWhenSignedIn which includes an api call to fetch
- * the user profile.
+ * If they are, it renders `DiscussionWhenSignedIn` which includes
+ * an API call to fetch the user profile.
  *
- * If not, it simply renders Discussion
+ * If not, it simply renders `Discussion`
  *
  * We use component composition like this here because you cannot call react
  * hooks conditionally and we're using a hook to make the fetch request
  *
  * Note. We allow the ...props pattern here because it makes sense when we're
  * just passing them through
  *
+ * ## Why does this need to be an Island?
+ *
+ * Discussion has client-side interactivity.
+ * Signed-in status is only known on the client.
+ *
+ * ---
+ *
+ * (No visual story exist)
  */
 
 export const DiscussionContainer = (props: DiscussionProps) => {

dotcom-rendering/src/components/GetMatchNav.importable.tsx

@@ -22,8 +22,6 @@ type Props = {
 const Loading = () => <Placeholder height={230} />;
 
 /**
- * # Get Match Nav
- *
  * Wrapper around `MatchNav` with loading and fallback.
  *
  * ## Why does this need to be an Island?

dotcom-rendering/src/components/GetMatchStats.importable.tsx

@@ -49,8 +49,6 @@ export const cleanTeamData = (team: TeamType): TeamType => ({
 });
 
 /**
- * # Get Match Stats
- *
  * Wrapper around `MatchStats`.
  *
  * ## Why does this need to be an Island?

dotcom-rendering/src/components/GetMatchTabs.importable.tsx

@@ -9,6 +9,15 @@ type Props = {
 
 const Loading = () => <Placeholder height={40} />;
 
+/**
+ * ## Why does this need to be an Island?
+ *
+ * Data is fetched from an API on the client-side.
+ *
+ * ---
+ *
+ * (No visual story exists)
+ */
 export const GetMatchTabs = ({ matchUrl, format }: Props) => {
 	const { data, error, loading } = useApi<{
 		reportUrl?: string;

dotcom-rendering/src/components/HeaderTopBar.importable.tsx

@@ -50,8 +50,6 @@ const topBarStylesFromLeftCol = css`
 `;
 
 /**
- * # Header Top Bar
- *
  * The slim dark blue top bar at the very top of Guardian pages
  *
  * ## Why does this need to be an Island?

dotcom-rendering/src/components/LatestLinks.importable.tsx

@@ -110,8 +110,6 @@ const extractAboutThreeLines = (text: string) =>
 				.join(' ') + '…'; // join with spaces and add an ellipsis
 
 /**
- * # Latest Links
- *
  * Display the last three blocks from a Liveblog when the fronts
  * tool has enabled showing live updates.
  *
@@ -122,7 +120,7 @@ const extractAboutThreeLines = (text: string) =>
  *
  * ---
  *
- * [`LatestLinks` on Chromatic](https://www.chromatic.com/component?appId=63e251470cfbe61776b0ef19&csfId=components-latestlinks)
+ * [`LatestLinks` on Chromatic](https://www.chromatic.com/component?appId=63e251470cfbe61776b0ef19&csfId=components-latestlinks&buildNumber=2967)
  */
 export const LatestLinks = ({
 	id,

dotcom-rendering/src/components/LightboxHash.importable.tsx

@@ -13,6 +13,14 @@ import { useOnce } from '../lib/useOnce';
  *
  * If we didn't do this then you'd end up back where you were when you pasted the
  * url into the browser and unable to access the article under the lightbox.
+ *
+ * ## Why does this need to be an Island?
+ *
+ * This behaviour is entirely client-side.
+ *
+ * ---
+ *
+ * Does not render **anything**.
  */
 export const LightboxHash = () => {
 	useOnce(() => {

dotcom-rendering/src/components/LiveBlogEpic.importable.tsx

@@ -233,6 +233,14 @@ function insertAfter(referenceNode: HTMLElement, newNode: Element) {
  * 2. Fetch - POST the payload to the contributions endpoint
  * 3. Render - Take the url, props and name data we got in response to our fetch and dynamically import
  *    and render the Epic component using it
+ *
+ * ## Why does this need to be an Island?
+ *
+ * All behaviour is client-side.
+ *
+ * ---
+ *
+ * (No visual story exist)
  */
 export const LiveBlogEpic = ({
 	sectionId,

dotcom-rendering/src/components/LiveblogRightMultipleAdSlots.importable.tsx

@@ -39,6 +39,14 @@ type Props = {
 /**
  * In the right hand column, there will be the right ad slot, followed
  * by as many liveblog-right ad slots that can fit
+ *
+ * ## Why does this need to be an Island?
+ *
+ * Ads are rendered client-side.
+ *
+ * ---
+ *
+ * (No visual story exists)
  */
 export const LiveblogRightMultipleAdSlots = ({
 	display,

dotcom-rendering/src/components/Liveness.importable.tsx

@@ -142,8 +142,6 @@ function getKey(
 }
 
 /**
- * # Liveness
- *
  * Allow new blocks on live blogs to be added without page reload.
  * Polls the content API inserts news blocks if the user
  * is at the top of the article.

dotcom-rendering/src/components/MostViewedFooter.importable.tsx

@@ -35,11 +35,15 @@ const secondTierStyles = css`
 `;
 
 /**
- * # Most Viewed Footer
- *
  * List of 10 most viewed articles to show at the bottom of pages.
  *
- * @Todo add Storybook link
+ * ## Why does this need to be an Island?
+ *
+ * Most viewed data if fetched client-side.
+ *
+ * ---
+ *
+ * (No visual story exists)
  */
 export const MostViewedFooter = ({
 	tabs,

dotcom-rendering/src/components/MostViewedRightWrapper.importable.tsx

@@ -11,7 +11,17 @@ type Props = {
 };
 
 /**
- * Wrapping MostViewedRight so we can determine whether or not there's enough vertical space in the container to render it
+ * Wrapping `MostViewedRight` so we can determine whether or not
+ * there's enough vertical space in the container to render it.
+ *
+ * ## Why does this need to be an Island?
+ *
+ * We may show the most viewed component depending on the length of the article,
+ * based on the computed height of the container.
+ *
+ * ---
+ *
+ * (No visual story exists)
  */
 export const MostViewedRightWrapper = ({
 	componentDataAttribute,

dotcom-rendering/src/components/OnwardsUpper.importable.tsx

@@ -173,8 +173,6 @@ type Props = {
 };
 
 /**
- * # Onwards Upper
- *
  * A wrapper around `Carousel` for showing related articles at the bottom
  * of an article. This contains the logic around which articles to show,
  * depending on a series of factors (story package, paid content, series tag, …)

dotcom-rendering/src/components/PulsingDot.importable.tsx

@@ -35,8 +35,6 @@ interface Props {
 }
 
 /**
- * # Pulsing Dot
- *
  * Used for indicating an article is updating live
  *
  * ## Why does this need to be an Island?

dotcom-rendering/src/components/RichLinkComponent.importable.tsx

@@ -53,8 +53,6 @@ const buildUrl: (element: RichLinkBlockElement, ajaxUrl: string) => string = (
 };
 
 /**
- * # Rich Link Component
- *
  * Wrapper around `RichLink` which fetches the rich links’ images.
  *
  * ## Why does this need to be an Island?

dotcom-rendering/src/components/SecureSignupIframe.importable.tsx

@@ -178,8 +178,6 @@ const sendTracking = (
 };
 
 /**
- * # Secure Signup iFrame
- *
  * A descendent of `EmailSignup` used to prevent users from entering their email
  * on the same page as the one we run third-party scripts on.
  *

dotcom-rendering/src/components/SendAMessage.importable.tsx

@@ -389,8 +389,6 @@ const summaryStyles = css`
 `;
 
 /**
- * # Send a Message Component
- *
  * A callout for readers to get in touch with a liveblogger directly.
  *
  * ## Why does this need to be an Island?

dotcom-rendering/src/components/SetABTests.importable.tsx

@@ -16,6 +16,17 @@ type Props = {
 	pageIsSensitive: CoreAPIConfig['pageIsSensitive'];
 };
 
+/**
+ * Initialises the values of `useAB` and sends relevant Ophan events.
+ *
+ * ## Why does this need to be an Island?
+ *
+ * All this logic is client-side.
+ *
+ * ---
+ *
+ * Does not render **anything**.
+ */
 export const SetABTests = ({
 	isDev,
 	pageIsSensitive,