feat: partial hydration

Author: avivkeller

package-lock.json

@@ -61,6 +61,7 @@
     "prettier": "3.8.5"
   },
   "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",

package.json

@@ -187,6 +187,8 @@ describe('web generate', () => {
           /export const server = false;/
         );
 
+        assert.match(entries.get('fs.jsx'), /registerIsland\("content"/);
+
         await Promise.all(
           [...pages].map(async ([fileName, html]) => {
             const path = join(output, fileName);

src/generators/web/__tests__/generate.test.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 } });

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

@@ -1,9 +1,9 @@
 import TableOfContents from '@node-core/ui-components/Common/TableOfContents';
 import Article from '@node-core/ui-components/Containers/Article';
 
+import Content from '../../islands/Content.jsx';
 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,15 +20,17 @@ import SideBar from '#theme/Sidebar';
  */
 export default ({ metadata, headings, readingTime, children }) => (
   <>
-    {!server && <Banner />}
+    <Banner />
     <NavBar metadata={metadata} />
     <Article>
       <SideBar metadata={metadata} />
       <div>
         <div>
           <TableOfContents headings={headings} summaryTitle="On this page" />
           <br />
-          <main>{children}</main>
+          <main>
+            <Content>{children}</Content>
+          </main>
         </div>
         <MetaBar
           metadata={metadata}

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

@@ -1,38 +1,30 @@
-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 } 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={[]}
+export default ({ metadata }) => (
+  <NavBar
+    Logo={Logo}
+    sidebarItemTogglerAriaLabel="Toggle navigation menu"
+    navItems={[]}
+  >
+    {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>
+);

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';
 
 const SearchBox = ({ pathname }) => {
@@ -59,4 +60,7 @@ const SearchBox = ({ pathname }) => {
   );
 };
 
-export default SearchBox;
+export default withIsland(SearchBox, {
+  name: 'SearchBox',
+  on: { interaction: 'pointerover,focusin,touchstart' },
+});

src/generators/web/ui/components/SearchBox/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 withIsland from '../../islands/withIsland.jsx';
 import { relativeOrAbsolute } from '../../utils/relativeOrAbsolute.mjs';
 
 import { project, version, versions, pages } from '#theme/config';
@@ -23,7 +24,7 @@ const redirect = url => (window.location.href = url);
  * Sidebar component for MDX documentation with version selection and page navigation
  * @param {{ metadata: import('../../types').SerializedMetadata }} props
  */
-export default ({ metadata }) => {
+const Sidebar = ({ metadata }) => {
   const introducedMajor = getMajorVersion(
     metadata.added ?? metadata.introduced_in
   );
@@ -65,3 +66,5 @@ export default ({ metadata }) => {
     </SideBar>
   );
 };
+
+export default withIsland(Sidebar, { name: 'SideBar', on: { idle: true } });

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

@@ -0,0 +1,20 @@
+import ThemeToggle from '@node-core/ui-components/Common/ThemeToggle';
+
+import { useTheme } from '../hooks/useTheme.mjs';
+import withIsland from '../islands/withIsland.jsx';
+
+/**
+ * Theme switcher.
+ */
+const Toggle = () => {
+  const [themePreference, setThemePreference] = useTheme();
+
+  return (
+    <ThemeToggle onChange={setThemePreference} currentTheme={themePreference} />
+  );
+};
+
+export default withIsland(Toggle, {
+  name: 'ThemeToggle',
+  on: { idle: true },
+});

src/generators/web/ui/components/ThemeToggle.jsx

@@ -10,6 +10,20 @@
   --font-ibm-plex-mono: 'IBM Plex Mono', monospace;
 }
 
+is-land {
+  display: contents;
+}
+
+/* TODO(@avivkeller): make this component's CSS more agnostic */
+is-land[data-component='SideBar'] {
+  display: flex;
+  flex-direction: column;
+
+  > aside {
+    flex: 1 0 auto;
+  }
+}
+
 main {
   /* Code should inherit its font size */
   code {