feat: partial hydration (#951)

* feat: partial hydration

* fixup!

Author: avivkeller

package-lock.json

@@ -53,12 +53,13 @@
     "README.md"
   ],
   "dependencies": {
+    "@11ty/is-land": "^5.0.1",
     "@actions/core": "^3.0.0",
     "@fontsource-variable/open-sans": "^5.3.0",
     "@fontsource/ibm-plex-mono": "^5.3.0",
     "@heroicons/react": "^2.2.0",
-    "@node-core/rehype-shiki": "^1.4.2",
-    "@node-core/ui-components": "^1.7.2",
+    "@node-core/rehype-shiki": "^1.4.3",
+    "@node-core/ui-components": "^1.7.4",
     "@orama/orama": "^3.1.18",
     "@orama/ui": "^1.5.4",
     "@swc/html-wasm": "^1.15.43",

packages/core/package.json

@@ -236,6 +236,12 @@ export const createViteConfig = ({
       ...(server ? { manifest: false } : {}),
       ssr: server,
 
+      // Islands make split CSS wrong: a component's stylesheet would arrive
+      // with the chunk that hydrates it, long after the server-rendered markup
+      // it styles is on screen. One stylesheet keeps the page styled from the
+      // first paint, whenever — or whether — its islands load.
+      ...(server ? {} : { cssCodeSplit: false }),
+
       // Browser output follows the generator's minification setting. Temporary
       // server output stays readable and disappears immediately after render.
       minify: server ? false : (vite.build?.minify ?? webConfig.minify),

packages/core/src/generators/web/bundlers/vite.mjs

@@ -24,7 +24,7 @@ export const JSX_IMPORTS = {
   },
   CodeTabs: {
     name: 'CodeTabs',
-    source: '@node-core/ui-components/MDX/CodeTabs',
+    source: resolve(ROOT, './ui/components/CodeTabs'),
   },
   MDXTooltip: {
     name: 'MDXTooltip',

packages/core/src/generators/web/constants.mjs

@@ -2,6 +2,7 @@ import { ArrowUpRightIcon } from '@heroicons/react/24/outline';
 import Banner from '@node-core/ui-components/Common/Banner';
 
 import useBanners from '../hooks/useBanners.mjs';
+import withIsland from '../islands/withIsland.jsx';
 
 import { remoteConfigUrl, version } from '#theme/config';
 
@@ -29,4 +30,4 @@ const Banners = () => {
   );
 };
 
-export default Banners;
+export default withIsland(Banners, { name: 'Banner', on: { idle: true } });

packages/core/src/generators/web/ui/components/Banner.jsx

@@ -1,5 +1,7 @@
 import BaseCodeBox from '@node-core/ui-components/Common/BaseCodeBox';
 
+import withIsland from '../islands/withIsland.jsx';
+
 import { languageDisplayNameMap } from '#theme/config';
 
 /**
@@ -15,7 +17,7 @@ export const getLanguageDisplayName = language => {
 };
 
 /** @param {import('react').PropsWithChildren<{ className: string }>} props */
-export default ({ className, ...props }) => {
+const CodeBox = ({ className, ...props }) => {
   const matches = className?.match(/language-(?<language>[a-zA-Z]+)/);
 
   const language = matches?.groups?.language ?? '';
@@ -31,3 +33,10 @@ export default ({ className, ...props }) => {
     />
   );
 };
+
+// The only interactive part is the copy button; the highlighted code itself is
+// static markup, so it stays in the server output and is never re-rendered.
+export default withIsland(CodeBox, {
+  name: 'CodeBox',
+  on: { interaction: 'pointerover,focusin,touchstart' },
+});

packages/core/src/generators/web/ui/components/CodeBox.jsx

@@ -0,0 +1,8 @@
+import CodeTabs from '@node-core/ui-components/MDX/CodeTabs';
+
+import withIsland from '../islands/withIsland.jsx';
+
+export default withIsland(CodeTabs, {
+  name: 'CodeTabs',
+  on: { interaction: 'pointerover,focusin,touchstart' },
+});

packages/core/src/generators/web/ui/components/CodeTabs.jsx

@@ -3,7 +3,6 @@ import Article from '@node-core/ui-components/Containers/Article';
 
 import Banner from '../Banner';
 
-import { server } from '#theme/config';
 import Footer from '#theme/Footer';
 import MetaBar from '#theme/Metabar';
 import NavBar from '#theme/Navigation';
@@ -20,7 +19,7 @@ import SideBar from '#theme/Sidebar';
  */
 export default ({ metadata, headings, readingTime, children }) => (
   <>
-    {!server && <Banner />}
+    <Banner />
     <NavBar metadata={metadata} />
     <Article>
       <SideBar metadata={metadata} />

packages/core/src/generators/web/ui/components/Layout/index.jsx

@@ -1,41 +1,33 @@
-import ThemeToggle from '@node-core/ui-components/Common/ThemeToggle';
 import NavBar from '@node-core/ui-components/Containers/NavBar';
 import styles from '@node-core/ui-components/Containers/NavBar/index.module.css';
 import GitHubIcon from '@node-core/ui-components/Icons/Social/GitHub';
 
 import SearchBox from './SearchBox';
-import { useTheme } from '../hooks/useTheme.mjs';
+import ThemeToggle from './ThemeToggle.jsx';
 
 import { repository, showSearchBox, navigation } from '#theme/config';
 import Logo from '#theme/Logo';
 
 /**
  * NavBar component that displays the headings, search, etc.
  */
-export default ({ metadata }) => {
-  const [themePreference, setThemePreference] = useTheme();
-
-  return (
-    <NavBar
-      Logo={Logo}
-      sidebarItemTogglerAriaLabel="Toggle navigation menu"
-      navItems={navigation.navbar ?? []}
-      // Drives the active-item highlight, and is dereferenced for every item
-      // whose link is site-absolute, so it must always be a string.
-      pathname={metadata.path}
+export default ({ metadata }) => (
+  <NavBar
+    Logo={Logo}
+    sidebarItemTogglerAriaLabel="Toggle navigation menu"
+    navItems={navigation.navbar ?? []}
+    // Drives the active-item highlight, and is dereferenced for every item
+    // whose link is site-absolute, so it must always be a string.
+    pathname={metadata.path}
+  >
+    {showSearchBox && <SearchBox pathname={metadata.path} />}
+    <ThemeToggle />
+    <a
+      href={`https://github.com/${repository}`}
+      aria-label={`View ${repository} on GitHub`}
+      className={styles.ghIconWrapper}
     >
-      {showSearchBox && <SearchBox pathname={metadata.path} />}
-      <ThemeToggle
-        onChange={setThemePreference}
-        currentTheme={themePreference}
-      />
-      <a
-        href={`https://github.com/${repository}`}
-        aria-label={`View ${repository} on GitHub`}
-        className={styles.ghIconWrapper}
-      >
-        <GitHubIcon />
-      </a>
-    </NavBar>
-  );
-};
+      <GitHubIcon />
+    </a>
+  </NavBar>
+);

packages/core/src/generators/web/ui/components/NavBar.jsx

@@ -9,6 +9,7 @@ import SearchHit from '@node-core/ui-components/Common/Search/Results/Hit';
 
 import styles from './index.module.css';
 import useOrama from '../../hooks/useOrama.mjs';
+import withIsland from '../../islands/withIsland.jsx';
 import { relativeOrAbsolute } from '../../utils/relativeOrAbsolute.mjs';
 
 /**
@@ -97,4 +98,7 @@ const SearchBox = ({ pathname }) => {
   );
 };
 
-export default SearchBox;
+export default withIsland(SearchBox, {
+  name: 'SearchBox',
+  on: { interaction: 'pointerover,focusin,touchstart' },
+});