fix(banner): prevent dismissal flicker before hydration

Author: trivikr

apps/site/app/[locale]/layout.tsx

@@ -1,3 +1,5 @@
+/* eslint-disable @eslint-react/dom-no-dangerously-set-innerhtml -- The script is static; banner data is escaped in data attributes. */
+
 import { availableLocales, defaultLocale } from '@node-core/website-i18n';
 import { Analytics } from '@vercel/analytics/react';
 import { SpeedInsights } from '@vercel/speed-insights/next';
@@ -7,14 +9,20 @@ import { NextIntlClientProvider } from 'next-intl';
 import BaseLayout from '#site/layouts/Base';
 import { VERCEL_ENV } from '#site/next.constants.mjs';
 import { IBM_PLEX_MONO, OPEN_SANS } from '#site/next.fonts';
+import { siteConfig } from '#site/next.json.mjs';
 import { ThemeProvider } from '#site/providers/themeProvider';
+import { BANNER_DISMISSAL_STORAGE_KEY } from '#site/util/banner';
 
 import type { FC, PropsWithChildren } from 'react';
 
 import '#site/styles/index.css';
 
 const fontClasses = classNames(IBM_PLEX_MONO.variable, OPEN_SANS.variable);
 
+const banner = siteConfig.websiteBanners.index;
+
+const bannerPreHydrationScript = `try{var s=document.currentScript;if(s&&localStorage.getItem(s.dataset.storageKey)===s.dataset.banner){document.documentElement.dataset.bannerDismissed='true'}}catch{}`;
+
 type RootLayoutProps = PropsWithChildren<{
   params: Promise<{ locale: string }>;
 }>;
@@ -32,6 +40,15 @@ const RootLayout: FC<RootLayoutProps> = async ({ children, params }) => {
       lang={hrefLang}
       suppressHydrationWarning
     >
+      <head>
+        {banner && (
+          <script
+            data-banner={banner.text}
+            data-storage-key={BANNER_DISMISSAL_STORAGE_KEY}
+            dangerouslySetInnerHTML={{ __html: bannerPreHydrationScript }}
+          />
+        )}
+      </head>
       <body suppressHydrationWarning>
         <NextIntlClientProvider>
           <ThemeProvider>

apps/site/components/withBanner.tsx

@@ -7,38 +7,40 @@ import { useEffect, useState } from 'react';
 
 import Link from '#site/components/Link';
 import { siteConfig } from '#site/next.json.mjs';
+import { BANNER_DISMISSAL_STORAGE_KEY } from '#site/util/banner';
 import { dateIsBetween } from '#site/util/date';
 
 import type { FC } from 'react';
 
-const STORAGE_KEY = 'banner-dismissal';
-
 const WithBanner: FC<{ section: string }> = ({ section }) => {
   const banner = siteConfig.websiteBanners[section];
   const t = useTranslations();
 
   const [dismissed, setDismissed] = useState(false);
 
-  // localStorage is only available on the client, so the banner is always
-  // rendered on the server and hidden after hydration if previously dismissed
+  // The pre-hydration script hides a dismissed banner before the first paint.
+  // This effect then synchronizes that state with React after hydration.
   useEffect(() => {
     if (banner) {
-      setDismissed(localStorage.getItem(STORAGE_KEY) === banner.text);
+      setDismissed(
+        localStorage.getItem(BANNER_DISMISSAL_STORAGE_KEY) === banner.text
+      );
     }
   }, [banner]);
 
   if (banner && !dismissed && dateIsBetween(banner.startDate, banner.endDate)) {
     const bannerType = banner.type || 'default';
 
     const onClose = () => {
-      localStorage.setItem(STORAGE_KEY, banner.text);
+      localStorage.setItem(BANNER_DISMISSAL_STORAGE_KEY, banner.text);
       setDismissed(true);
     };
 
     return (
       <Banner
         type={banner.type}
         aria-label={t(`components.banner.${bannerType}`)}
+        data-dismissible-banner=""
         onClose={onClose}
       >
         {banner.link ? (

apps/site/styles/index.css

@@ -10,6 +10,10 @@
 @import '@node-core/ui-components/src/styles/index.css';
 @import '@node-core/rehype-shiki/index.css';
 
+html[data-banner-dismissed='true'] [data-dismissible-banner] {
+  display: none;
+}
+
 /**
  * To enhance readability for Korean users, line spacing is increased,
  * line breaks in the middle of words are prevented, and long words are

apps/site/util/banner.ts

@@ -0,0 +1 @@
+export const BANNER_DISMISSAL_STORAGE_KEY = 'banner-dismissal';