feat: allow for specifying versions in config (#1110)

Author: avivkeller

.changeset/remote-config-versions.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/generator-react': minor
+---
+
+feat(html): fetch the remote config once through a `useRemoteConfig` hook, and let its `versions` key replace the build-time version selector entries

packages/react/src/html/README.md

@@ -30,7 +30,10 @@ from the module pages' compiled content rather than built again from scratch.
 - `pageURL` {string} URL template for documentation page links.
   **Default:** `'{baseURL}{path}.html'`.
 - `remoteConfigUrl` {string} URL fetched client-side at runtime for remote site
-  config (currently used to power the announcement banner).
+  config. Its `websiteBanners` power the announcement banner, and its
+  `versions` (same shape as the `versions` export below) replace the build-time
+  version selector entries, so docs built for an older release still list the
+  releases that came after it.
   **Default:** none — no runtime fetch, no banner.
 - `head` {Object} Configurable `<meta>`, `<link>`, and raw markup for the
   document head. See [`head`](#head).
@@ -434,7 +437,7 @@ path, items? }` entries nested by heading depth, in document order. Empty
 - `languageDisplayNameMap` {Map<string, string>} Shiki language alias → display
   name map for code blocks.
 - `remoteConfigUrl` {string} Mirrors the configured `remoteConfigUrl` (fetched
-  client-side by `RemoteLoadableBanner` to load announcement banners).
+  client-side by the `useRemoteConfig` hook for the banner and version selector).
 - `server` {boolean} Whether the current bundle is the server build.
 
 ### Usage in custom components

packages/react/src/html/ui/components/Banner.jsx

@@ -2,12 +2,17 @@ import { ArrowUpRightIcon } from '@heroicons/react/24/outline';
 import Banner from '@node-core/ui-components/Common/Banner';
 
 import useBanners from '../hooks/useBanners.mjs';
+import useRemoteConfig from '../hooks/useRemoteConfig.mjs';
 import withIsland from '../islands/withIsland.jsx';
 
-import { remoteConfigUrl, version } from '#theme/config';
+import { version } from '#theme/config';
 
 const Banners = () => {
-  const [banner, dismissBanner] = useBanners(remoteConfigUrl, version.major);
+  const remote = useRemoteConfig();
+  const [banner, dismissBanner] = useBanners(
+    remote?.websiteBanners,
+    version.major
+  );
 
   return (
     banner && (

packages/react/src/html/ui/components/SideBar/index.jsx

@@ -2,6 +2,7 @@ import Select from '@node-core/ui-components/Common/Select';
 import SideBar from '@node-core/ui-components/Containers/Sidebar';
 
 import styles from './index.module.css';
+import useRemoteConfig from '../../hooks/useRemoteConfig.mjs';
 import withIsland from '../../islands/withIsland.jsx';
 import { relativeOrAbsolute } from '../../utils/relativeOrAbsolute.mjs';
 import { renderLabel } from '../../utils/renderLabel.jsx';
@@ -109,8 +110,12 @@ const Sidebar = ({ metadata }) => {
     metadata.added ?? metadata.introduced_in
   );
 
-  // Filter pre-computed versions by compatibility and resolve per-page URL
-  const compatibleVersions = versions
+  // A remote config's `versions` supersede the build-time list
+  const remote = useRemoteConfig();
+  const availableVersions = remote?.versions ?? versions;
+
+  // Filter versions by compatibility and resolve per-page URL
+  const compatibleVersions = availableVersions
     .filter(v => v.major >= introducedMajor)
     .map(({ url, label }) => ({
       value: url.replace('{path}', metadata.path),
@@ -126,7 +131,7 @@ const Sidebar = ({ metadata }) => {
       title="Navigation"
     >
       {/* A site built without a `changelog` has no versions to switch between. */}
-      {versions.length > 0 && (
+      {availableVersions.length > 0 && (
         <div>
           <Select
             label={`${project} version`}

packages/react/src/html/ui/hooks/useBanners.mjs

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback, useMemo, useState } from 'react';
 
 const STORAGE_KEY = 'banner-dismissal';
 
@@ -38,23 +38,14 @@ export const isBannerActive = ({ startDate, endDate }) => {
 };
 
 /**
- * Fetches the first active banner, preferring the global banner over
+ * Finds the first active banner, preferring the global banner over
  * the version-specific one.
  *
- * @param {string | undefined} remoteConfigUrl
+ * @param {Record<string, BannerEntry> | undefined} websiteBanners
  * @param {number | null} versionMajor
- * @returns {Promise<ActiveBanner | null>}
+ * @returns {ActiveBanner | null}
  */
-export const loadBanner = async (remoteConfigUrl, versionMajor) => {
-  if (!remoteConfigUrl) {
-    return null;
-  }
-
-  const response = await fetch(remoteConfigUrl);
-
-  /** @type {{ websiteBanners?: Record<string, BannerEntry> }} */
-  const { websiteBanners = {} } = await response.json();
-
+export const findBanner = (websiteBanners = {}, versionMajor) => {
   const sections =
     versionMajor == null ? ['index'] : ['index', `v${versionMajor}`];
 
@@ -86,42 +77,32 @@ export const saveBannerDismissal = banner =>
   localStorage.setItem(getStorageKey(banner.section), banner.text);
 
 /**
- * Loads, filters, and dismisses the announcement banner.
+ * Selects, filters, and dismisses the announcement banner.
  *
- * @param {string | undefined} remoteConfigUrl
+ * @param {Record<string, BannerEntry> | undefined} websiteBanners
  * @param {number | null} versionMajor
  * @returns {[ActiveBanner | null, () => void]}
  */
-export default (remoteConfigUrl, versionMajor) => {
-  const [banner, setBanner] = useState(
-    /** @type {ActiveBanner | null} */ (null)
-  );
+export default (websiteBanners, versionMajor) => {
+  // Only re-renders the banner away; the dismissal itself lives in storage
+  const [dismissed, setDismissed] = useState(false);
 
-  useEffect(() => {
-    let mounted = true;
-
-    loadBanner(remoteConfigUrl, versionMajor)
-      .then(loaded => {
-        if (mounted) {
-          setBanner(loaded && !isBannerDismissed(loaded) ? loaded : null);
-        }
-      })
-      .catch(() => {});
+  const found = useMemo(
+    () => (websiteBanners ? findBanner(websiteBanners, versionMajor) : null),
+    [websiteBanners, versionMajor]
+  );
 
-    return () => {
-      mounted = false;
-    };
-  }, [remoteConfigUrl, versionMajor]);
+  // `found` is only set client-side, once the remote config has loaded
+  const banner =
+    found && !dismissed && !isBannerDismissed(found) ? found : null;
 
   const dismissBanner = useCallback(() => {
-    setBanner(current => {
-      if (current) {
-        saveBannerDismissal(current);
-      }
-
-      return null;
-    });
-  }, []);
+    if (found) {
+      saveBannerDismissal(found);
+    }
+
+    setDismissed(true);
+  }, [found]);
 
   return [banner, dismissBanner];
 };

packages/react/src/html/ui/hooks/useRemoteConfig.mjs

@@ -0,0 +1,52 @@
+import { useEffect, useState } from 'react';
+
+import { remoteConfigUrl } from '#theme/config';
+
+/**
+ * The site configuration fetched at runtime from `remoteConfigUrl`.
+ *
+ * Every key is optional: a remote config only overrides what it provides.
+ *
+ * @typedef {object} RemoteConfig
+ * @property {Record<string, import('./useBanners.mjs').BannerEntry>} [websiteBanners]
+ * Announcement banners, keyed by `index` (global) or `v{major}`.
+ * @property {typeof import('#theme/config').versions} [versions]
+ * Version entries for the version selector, in the same shape as the
+ * build-time `versions` export. When present, they replace the build-time
+ * list so that docs built for an older release still list current releases.
+ */
+
+/**
+ * Fetches the remote site configuration once the component mounts.
+ *
+ * @returns {RemoteConfig | null} `null` until loaded, or when there is no
+ * `remoteConfigUrl` or the fetch fails.
+ */
+export default () => {
+  const [config, setConfig] = useState(
+    /** @type {RemoteConfig | null} */ (null)
+  );
+
+  useEffect(() => {
+    if (!remoteConfigUrl) {
+      return;
+    }
+
+    let mounted = true;
+
+    fetch(remoteConfigUrl)
+      .then(response => response.json())
+      .then(loaded => {
+        if (mounted) {
+          setConfig(loaded);
+        }
+      })
+      .catch(() => {});
+
+    return () => {
+      mounted = false;
+    };
+  }, []);
+
+  return config;
+};