feat: create announcements banner

package.json

@@ -12,7 +12,7 @@
     "format": "prettier .",
     "format:write": "prettier --write .",
     "format:check": "prettier --check .",
-    "test": "node --test --experimental-test-module-mocks \"src/**/*.test.mjs\"",
+    "test": "node --test --experimental-test-module-mocks --import=global-jsdom/register \"src/**/*.test.mjs\"",
     "test:coverage": "c8 node --test --experimental-test-module-mocks \"src/**/*.test.mjs\"",
     "test:ci": "c8 --reporter=lcov node --test --experimental-test-module-mocks \"src/**/*.test.mjs\" --test-reporter=@reporters/github --test-reporter-destination=stdout --test-reporter=junit --test-reporter-destination=junit.xml --test-reporter=spec --test-reporter-destination=stdout",
     "test:update-snapshots": "node --test --experimental-test-module-mocks --test-update-snapshots \"src/**/*.test.mjs\"",
@@ -28,6 +28,8 @@
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@reporters/github": "^1.12.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/mdast": "^4.0.4",
     "@types/node": "^24.10.1",
     "@types/semver": "^7.7.1",
@@ -37,7 +39,9 @@
     "eslint-plugin-import-x": "^4.16.1",
     "eslint-plugin-jsdoc": "^62.4.1",
     "eslint-plugin-react-x": "^2.8.1",
+    "global-jsdom": "^29.0.0",
     "husky": "^9.1.7",
+    "jsdom": "^29.0.1",
     "lint-staged": "^16.2.7",
     "prettier": "3.8.1"
   },

src/generators/jsx-ast/index.mjs

@@ -21,6 +21,7 @@ export default createLazyGenerator({
     ref: 'main',
     pageURL: '{baseURL}/latest-{version}/api{path}.html',
     editURL: `${GITHUB_EDIT_URL}/doc/api{path}.md`,
+    remoteConfig: 'https://nodejs.org/site.json',
   },
 
   hasParallelProcessor: true,

src/generators/jsx-ast/utils/buildContent.mjs

@@ -291,14 +291,21 @@ export const createDocumentLayout = (
   sideBarProps,
   metaBarProps,
   remark
-) =>
-  createTree('root', [
+) => {
+  const config = getConfig('jsx-ast');
+
+  return createTree('root', [
     createJSXElement(JSX_IMPORTS.Layout.name, {
       sideBarProps,
       metaBarProps,
+      announcementBannerProps: {
+        remoteConfig: config.remoteConfig,
+        versionMajor: config.version?.major ?? null,
+      },
       children: entries.map(entry => processEntry(entry, remark)),
     }),
   ]);
+};
 
 /**
  * @typedef {import('estree').Node & { data: import('../../metadata/types').MetadataEntry }} JSXContent

src/generators/web/types.d.ts

@@ -5,6 +5,7 @@ export type Generator = GeneratorMetadata<
     templatePath: string;
     title: string;
     imports: Record<string, string>;
+    remoteConfig: string;
   },
   Generate<Array<JSXContent>, AsyncGenerator<{ html: string; css: string }>>
 >;

src/generators/web/ui/components/AnnouncementBanner/__tests__/useBanners.test.mjs

@@ -0,0 +1,174 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { loadBanners } from '../loadBanners.mjs';
+
+const PAST = new Date(Date.now() - 86_400_000).toISOString(); // yesterday
+const FUTURE = new Date(Date.now() + 86_400_000).toISOString(); // tomorrow
+
+const makeResponse = (banners, ok = true) => ({
+  ok,
+  json: async () => ({ websiteBanners: banners }),
+});
+
+describe('loadBanners', () => {
+  describe('fetch behavior', () => {
+    it('fetches from the given URL', async t => {
+      t.mock.method(global, 'fetch', () => Promise.resolve(makeResponse({})));
+
+      await loadBanners('https://example.com/site.json', null);
+
+      assert.equal(global.fetch.mock.calls.length, 1);
+      assert.equal(
+        global.fetch.mock.calls[0].arguments[0],
+        'https://example.com/site.json'
+      );
+    });
+
+    it('returns an empty array on non-ok response', async t => {
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve(makeResponse({}, false))
+      );
+
+      const result = await loadBanners('https://example.com/site.json', null);
+
+      assert.deepEqual(result, []);
+    });
+
+    it('handles fetch errors silently', async t => {
+      t.mock.method(global, 'fetch', () =>
+        Promise.reject(new Error('Network error'))
+      );
+
+      const result = await loadBanners('https://example.com/site.json', null);
+
+      assert.deepEqual(result, []);
+    });
+
+    it('returns an empty array when remoteConfig is absent', async t => {
+      t.mock.method(global, 'fetch', () => Promise.resolve(makeResponse({})));
+
+      const result = await loadBanners(undefined, null);
+
+      assert.deepEqual(result, []);
+      assert.equal(global.fetch.mock.calls.length, 0);
+    });
+  });
+
+  describe('banner selection', () => {
+    it('returns the active global (index) banner', async t => {
+      const banner = { text: 'Global banner', type: 'warning' };
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve(makeResponse({ index: banner }))
+      );
+
+      const result = await loadBanners('https://example.com/site.json', null);
+
+      assert.deepEqual(result, [banner]);
+    });
+
+    it('returns the active version-specific banner', async t => {
+      const banner = { text: 'v20 banner', type: 'warning' };
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve(makeResponse({ v20: banner }))
+      );
+
+      const result = await loadBanners('https://example.com/site.json', 20);
+
+      assert.deepEqual(result, [banner]);
+    });
+
+    it('returns both global and version banners when both are active', async t => {
+      const globalBanner = { text: 'Global banner', type: 'warning' };
+      const versionBanner = { text: 'v20 banner', type: 'error' };
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve(
+          makeResponse({ index: globalBanner, v20: versionBanner })
+        )
+      );
+
+      const result = await loadBanners('https://example.com/site.json', 20);
+
+      assert.deepEqual(result, [globalBanner, versionBanner]);
+    });
+
+    it('returns global banner first, version banner second', async t => {
+      const globalBanner = { text: 'Global', type: 'warning' };
+      const versionBanner = { text: 'v22', type: 'error' };
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve(
+          makeResponse({ index: globalBanner, v22: versionBanner })
+        )
+      );
+
+      const result = await loadBanners('https://example.com/site.json', 22);
+
+      assert.equal(result[0], globalBanner);
+      assert.equal(result[1], versionBanner);
+    });
+
+    it('does not include the version banner when versionMajor is null', async t => {
+      const globalBanner = { text: 'Global banner', type: 'warning' };
+      const versionBanner = { text: 'v20 banner', type: 'error' };
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve(
+          makeResponse({ index: globalBanner, v20: versionBanner })
+        )
+      );
+
+      const result = await loadBanners('https://example.com/site.json', null);
+
+      assert.deepEqual(result, [globalBanner]);
+    });
+
+    it('returns an empty array when websiteBanners is absent', async t => {
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve({ ok: true, json: async () => ({}) })
+      );
+
+      const result = await loadBanners('https://example.com/site.json', null);
+
+      assert.deepEqual(result, []);
+    });
+  });
+
+  describe('date filtering', () => {
+    it('excludes a banner whose endDate has passed', async t => {
+      const banner = { text: 'Expired', type: 'warning', endDate: PAST };
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve(makeResponse({ index: banner }))
+      );
+
+      const result = await loadBanners('https://example.com/site.json', null);
+
+      assert.deepEqual(result, []);
+    });
+
+    it('excludes a banner whose startDate is in the future', async t => {
+      const banner = { text: 'Upcoming', type: 'warning', startDate: FUTURE };
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve(makeResponse({ index: banner }))
+      );
+
+      const result = await loadBanners('https://example.com/site.json', null);
+
+      assert.deepEqual(result, []);
+    });
+
+    it('includes a banner within its active date range', async t => {
+      const banner = {
+        text: 'Active',
+        type: 'warning',
+        startDate: PAST,
+        endDate: FUTURE,
+      };
+      t.mock.method(global, 'fetch', () =>
+        Promise.resolve(makeResponse({ index: banner }))
+      );
+
+      const result = await loadBanners('https://example.com/site.json', null);
+
+      assert.deepEqual(result, [banner]);
+    });
+  });
+});

src/generators/web/ui/components/AnnouncementBanner/index.jsx

@@ -0,0 +1,56 @@
+import { ArrowUpRightIcon } from '@heroicons/react/24/outline';
+import Banner from '@node-core/ui-components/Common/Banner';
+import { lazy, Suspense } from 'preact/compat';
+import { useMemo } from 'preact/hooks';
+
+import styles from './index.module.css';
+import { loadBanners } from './loadBanners.mjs';
+
+/** @import { BannerEntry } from './types.d.ts' */
+
+/**
+ * @param {{ banners: BannerEntry[] }} props
+ */
+const AnnouncementBanner = ({ banners }) => (
+  <div role="region" aria-label="Announcements" className={styles.banners}>
+    {banners.map(banner => (
+      <Banner key={banner.text} type={banner.type}>
+        {banner.link ? (
+          <a href={banner.link} target="_blank" rel="noopener noreferrer">
+            {banner.text}
+          </a>
+        ) : (
+          banner.text
+        )}
+        {banner.link && <ArrowUpRightIcon />}
+      </Banner>
+    ))}
+  </div>
+);
+
+export default AnnouncementBanner;
+
+/**
+ * @param {{ remoteConfig: string, versionMajor: number | null }} props
+ */
+export const RemoteLoadableBanner = ({ remoteConfig, versionMajor }) => {
+  const LazyBanners = useMemo(
+    () =>
+      lazy(async () => {
+        const active = await loadBanners(remoteConfig, versionMajor);
+
+        if (!active.length) {
+          return { default: () => null };
+        }
+
+        return { default: () => <AnnouncementBanner banners={active} /> };
+      }),
+    []
+  );
+
+  return (
+    <Suspense fallback={null}>
+      <LazyBanners />
+    </Suspense>
+  );
+};

src/generators/web/ui/components/AnnouncementBanner/index.module.css

@@ -0,0 +1,14 @@
+.banners {
+  animation: slideDown 300ms ease-out 400ms backwards;
+}
+
+@keyframes slideDown {
+  from {
+    opacity: 0;
+    transform: translateY(-0.5rem);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}

src/generators/web/ui/components/AnnouncementBanner/loadBanners.mjs

@@ -0,0 +1,40 @@
+import { isBannerActive } from '../../utils/banner.mjs';
+
+/** @import { BannerEntry, RemoteConfig } from './types.d.ts' */
+
+/**
+ * Fetches and returns active banners for the given version.
+ * Returns an empty array when remoteConfig is absent, the response is not ok,
+ * or on any fetch/parse failure.
+ *
+ * @param {string | undefined} remoteConfig
+ * @param {number | null} versionMajor
+ * @returns {Promise<BannerEntry[]>}
+ */
+export const loadBanners = async (remoteConfig, versionMajor) => {
+  if (!remoteConfig) {
+    return [];
+  }
+
+  try {
+    const res = await fetch(remoteConfig, {
+      signal: AbortSignal.timeout(2500),
+    });
+    if (!res.ok) {
+      return [];
+    }
+
+    /** @type {RemoteConfig} */
+    const { websiteBanners = {} } = await res.json();
+
+    const keys = ['index', versionMajor != null && `v${versionMajor}`].filter(
+      Boolean
+    );
+
+    return keys
+      .map(key => websiteBanners[key])
+      .filter(banner => banner && isBannerActive(banner));
+  } catch {
+    return [];
+  }
+};

src/generators/web/ui/components/AnnouncementBanner/types.d.ts

@@ -0,0 +1,22 @@
+import type { BannerProps } from '@node-core/ui-components/Common/Banner';
+
+export type BannerEntry = {
+  startDate?: string;
+  endDate?: string;
+  text: string;
+  link?: string;
+  type?: BannerProps['type'];
+};
+
+export type RemoteConfig = {
+  websiteBanners?: Record<string, BannerEntry | undefined>;
+};
+
+export type AnnouncementBannerProps = {
+  banners: BannerEntry[];
+};
+
+export type RemoteLoadableBannerProps = {
+  remoteConfig: string;
+  versionMajor: number | null;
+};