@myst-theme/site 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myst-theme/site",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -21,23 +21,23 @@
   "dependencies": {
     "@headlessui/react": "^1.7.15",
     "@heroicons/react": "^2.0.18",
-    "@myst-theme/common": "^0.10.0",
-    "@myst-theme/diagrams": "^0.10.0",
-    "@myst-theme/frontmatter": "^0.10.0",
-    "@myst-theme/jupyter": "^0.10.0",
-    "@myst-theme/providers": "^0.10.0",
+    "@myst-theme/common": "^0.12.0",
+    "@myst-theme/diagrams": "^0.12.0",
+    "@myst-theme/frontmatter": "^0.12.0",
+    "@myst-theme/jupyter": "^0.12.0",
+    "@myst-theme/providers": "^0.12.0",
     "@radix-ui/react-collapsible": "^1.0.3",
     "classnames": "^2.3.2",
     "lodash.throttle": "^4.1.1",
-    "myst-common": "^1.5.0",
-    "myst-config": "^1.5.0",
-    "myst-demo": "^0.10.0",
-    "myst-spec-ext": "^1.5.0",
-    "myst-to-react": "^0.10.0",
+    "myst-common": "^1.6.0",
+    "myst-config": "^1.6.0",
+    "myst-demo": "^0.12.0",
+    "myst-spec-ext": "^1.6.0",
+    "myst-to-react": "^0.12.0",
     "nbtx": "^0.2.3",
     "node-cache": "^5.1.2",
     "node-fetch": "^2.6.11",
-    "thebe-react": "0.4.7",
+    "thebe-react": "0.4.10",
     "unist-util-select": "^4.0.1"
   },
   "peerDependencies": {

package/src/actions/index.ts

@@ -0,0 +1 @@
+export * from './theme.js';

package/src/actions/theme.ts

@@ -0,0 +1,8 @@
+import type { Theme } from '@myst-theme/common';
+
+export function postThemeToAPI(theme: Theme) {
+  const xmlhttp = new XMLHttpRequest();
+  xmlhttp.open('POST', '/api/theme');
+  xmlhttp.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
+  xmlhttp.send(JSON.stringify({ theme }));
+}

package/src/components/Navigation/PrimarySidebar.tsx

@@ -6,6 +6,7 @@ import {
   useSiteManifest,
   useGridSystemProvider,
   useThemeTop,
+  useIsWide,
 } from '@myst-theme/providers';
 import type { Heading } from '@myst-theme/common';
 import { Toc } from './TableOfContentsItems.js';
@@ -95,10 +96,15 @@ export function useSidebarHeight<T extends HTMLElement = HTMLElement>(top = 0, i
   const container = useRef<T>(null);
   const toc = useRef<HTMLDivElement>(null);
   const transitionState = useNavigation().state;
+  const wide = useIsWide();
   const setHeight = () => {
     if (!container.current || !toc.current) return;
     const height = container.current.offsetHeight - window.scrollY;
     const div = toc.current.firstChild as HTMLDivElement;
+    if (div)
+      div.style.height = wide
+        ? `min(calc(100vh - ${top}px), ${height + inset}px)`
+        : `calc(100vh - ${top}px)`;
     if (div) div.style.height = `min(calc(100vh - ${top}px), ${height + inset}px)`;
     const nav = toc.current.querySelector('nav');
     if (nav) nav.style.opacity = height > 150 ? '1' : '0';
@@ -111,7 +117,7 @@ export function useSidebarHeight<T extends HTMLElement = HTMLElement>(top = 0, i
     return () => {
       window.removeEventListener('scroll', handleScroll);
     };
-  }, [container, toc, transitionState]);
+  }, [container, toc, transitionState, wide]);
   return { container, toc };
 }
 

package/src/components/Navigation/ThemeButton.tsx

@@ -1,25 +1,22 @@
-import { useTheme } from '@myst-theme/providers';
+import { useThemeSwitcher } from '@myst-theme/providers';
 import { MoonIcon } from '@heroicons/react/24/solid';
 import { SunIcon } from '@heroicons/react/24/outline';
 import classNames from 'classnames';
 
 export function ThemeButton({ className = 'w-8 h-8 mx-3' }: { className?: string }) {
-  const { isDark, nextTheme } = useTheme();
+  const { nextTheme } = useThemeSwitcher();
   return (
     <button
       className={classNames(
         'theme rounded-full border border-stone-700 dark:border-white hover:bg-neutral-100 border-solid overflow-hidden text-stone-700 dark:text-white hover:text-stone-500 dark:hover:text-neutral-800',
         className,
       )}
-      title={`Change theme to ${isDark ? 'light' : 'dark'} mode.`}
-      aria-label={`Change theme to ${isDark ? 'light' : 'dark'} mode.`}
+      title={`Toggle theme between light and dark mode.`}
+      aria-label={`Toggle theme between light and dark mode.`}
       onClick={nextTheme}
     >
-      {isDark ? (
-        <MoonIcon className="h-full w-full p-0.5" />
-      ) : (
-        <SunIcon className="h-full w-full p-0.5" />
-      )}
+      <MoonIcon className="h-full w-full p-0.5 hidden dark:block" />
+      <SunIcon className="h-full w-full p-0.5 dark:hidden" />
     </button>
   );
 }

package/src/components/index.ts

@@ -18,3 +18,4 @@ export { ExternalOrInternalLink } from './ExternalOrInternalLink.js';
 export * from './Navigation/index.js';
 export { renderers } from './renderers.js';
 export { SkipToArticle, SkipTo } from './SkipToArticle.js';
+export { BlockingThemeLoader } from './theme.js';

package/src/components/renderers.ts

@@ -1,10 +1,10 @@
-import type { NodeRenderer } from '@myst-theme/providers';
+import type { NodeRenderers } from '@myst-theme/providers';
 import { DEFAULT_RENDERERS } from 'myst-to-react';
 import { MystDemoRenderer } from 'myst-demo';
 import { MermaidNodeRenderer } from '@myst-theme/diagrams';
 import OUTPUT_RENDERERS from '@myst-theme/jupyter';
 
-export const renderers: Record<string, NodeRenderer> = {
+export const renderers: NodeRenderers = {
   ...DEFAULT_RENDERERS,
   myst: MystDemoRenderer,
   mermaid: MermaidNodeRenderer,

package/src/components/theme.tsx

@@ -0,0 +1,19 @@
+import { THEME_LOCALSTORAGE_KEY, PREFERS_LIGHT_MQ } from '../hooks/theme.js';
+
+/**
+ * A blocking element that runs on the client before hydration to update the <html> preferred class
+ * This ensures that the hydrated state matches the non-hydrated state (by updating the DOM on the
+ * client between SSR on the server and hydration on the client)
+ */
+export function BlockingThemeLoader({ useLocalStorage }: { useLocalStorage: boolean }) {
+  const LOCAL_STORAGE_SOURCE = `localStorage.getItem(${JSON.stringify(THEME_LOCALSTORAGE_KEY)})`;
+  const CLIENT_THEME_SOURCE = `
+  const savedTheme = ${useLocalStorage ? LOCAL_STORAGE_SOURCE : 'null'};
+  const theme = window.matchMedia(${JSON.stringify(PREFERS_LIGHT_MQ)}).matches ? 'light' : 'dark';
+  const classes = document.documentElement.classList;
+  const hasAnyTheme = classes.contains('light') || classes.contains('dark');
+  if (!hasAnyTheme) classes.add(savedTheme ?? theme);
+`;
+
+  return <script dangerouslySetInnerHTML={{ __html: CLIENT_THEME_SOURCE }} />;
+}

package/src/hooks/index.ts

@@ -0,0 +1 @@
+export * from './theme.js';

package/src/hooks/theme.tsx

@@ -0,0 +1,84 @@
+import React, { useEffect, useRef } from 'react';
+import { Theme } from '@myst-theme/common';
+import { isTheme } from '@myst-theme/providers';
+import { postThemeToAPI } from '../actions/theme.js';
+
+export const PREFERS_LIGHT_MQ = '(prefers-color-scheme: light)';
+export const THEME_LOCALSTORAGE_KEY = 'myst:theme';
+
+export function getPreferredTheme() {
+  if (typeof window !== 'object') {
+    return null;
+  }
+  const mediaQuery = window.matchMedia(PREFERS_LIGHT_MQ);
+  return mediaQuery.matches ? Theme.light : Theme.dark;
+}
+
+/**
+ * Hook that changes theme to follow changes to system preference.
+ */
+export function usePreferredTheme({ setTheme }: { setTheme: (theme: Theme | null) => void }) {
+  // Listen for system-updates that change the preferred theme
+  // This will modify the saved theme
+  useEffect(() => {
+    const mediaQuery = window.matchMedia(PREFERS_LIGHT_MQ);
+    const handleChange = () => {
+      setTheme(mediaQuery.matches ? Theme.light : Theme.dark);
+    };
+    mediaQuery.addEventListener('change', handleChange);
+    return () => mediaQuery.removeEventListener('change', handleChange);
+  }, []);
+}
+
+export function useTheme({
+  ssrTheme,
+  useLocalStorage,
+}: {
+  ssrTheme?: Theme;
+  useLocalStorage?: boolean;
+}): [Theme | null, (theme: Theme) => void] {
+  // Here, the initial state on the server without any set cookies will be null.
+  // The client will then load the initial state as non-null.
+  // Thus, we must mutate the DOM *pre-hydration* to ensure that the initial state is
+  // identical to that of the hydrated state, i.e. perform out-of-react DOM updates
+  // This is handled by the BlockingThemeLoader component.
+  const [theme, setTheme] = React.useState<Theme | null>(() => {
+    if (isTheme(ssrTheme)) {
+      return ssrTheme;
+    }
+    // On the server we can't know what the preferred theme is, so leave it up to client
+    if (typeof window !== 'object') {
+      return null;
+    }
+    // System preferred theme
+    const preferredTheme = getPreferredTheme();
+
+    // Local storage preferred theme
+    const savedTheme = localStorage.getItem(THEME_LOCALSTORAGE_KEY);
+    return useLocalStorage && isTheme(savedTheme) ? savedTheme : preferredTheme;
+  });
+
+  // Listen for system-updates that change the preferred theme
+  usePreferredTheme({ setTheme });
+
+  // Listen for changes to theme, and propagate to server
+  // This should be unidirectional; updates to the cookie do not trigger document rerenders
+  const mountRun = useRef(false);
+  useEffect(() => {
+    // Only update after the component is mounted (i.e. don't send initial state)
+    if (!mountRun.current) {
+      mountRun.current = true;
+      return;
+    }
+    if (!isTheme(theme)) {
+      return;
+    }
+    if (useLocalStorage) {
+      localStorage.setItem(THEME_LOCALSTORAGE_KEY, theme);
+    } else {
+      postThemeToAPI(theme);
+    }
+  }, [theme]);
+
+  return [theme, setTheme];
+}

package/src/index.ts

@@ -1,6 +1,8 @@
 export * from './utils.js';
 export * from './loaders/index.js';
 export * from './components/index.js';
+export * from './hooks/index.js';
 export * from './pages/index.js';
 export * from './seo/index.js';
 export * from './themeCSS.js';
+export * from './actions/index.js';

package/src/loaders/theme.server.ts

@@ -1,5 +1,6 @@
 import { createCookieSessionStorage, json } from '@remix-run/node';
-import { isTheme, Theme } from '@myst-theme/providers';
+import { isTheme } from '@myst-theme/providers';
+import type { Theme } from '@myst-theme/providers';
 import type { ActionFunction } from '@remix-run/node';
 
 export const themeStorage = createCookieSessionStorage({
@@ -18,7 +19,7 @@ async function getThemeSession(request: Request) {
   return {
     getTheme: () => {
       const themeValue = session.get('theme');
-      return isTheme(themeValue) ? themeValue : Theme.light;
+      return isTheme(themeValue) ? themeValue : undefined;
     },
     setTheme: (theme: Theme) => session.set('theme', theme),
     commit: () => themeStorage.commitSession(session, { expires: new Date('2100-01-01') }),

package/src/pages/Article.tsx

@@ -7,8 +7,6 @@ import {
   FrontmatterParts,
   BackmatterParts,
 } from '../components/index.js';
-import { ErrorDocumentNotFound } from './ErrorDocumentNotFound.js';
-import { ErrorProjectNotFound } from './ErrorProjectNotFound.js';
 import type { PageLoader } from '@myst-theme/common';
 import { copyNode, type GenericParent } from 'myst-common';
 import { SourceFileKind } from 'myst-spec-ext';
@@ -80,11 +78,3 @@ export const ArticlePage = React.memo(function ({
     </ReferencesProvider>
   );
 });
-
-export function ProjectPageCatchBoundary() {
-  return <ErrorProjectNotFound />;
-}
-
-export function ArticlePageCatchBoundary() {
-  return <ErrorDocumentNotFound />;
-}

package/src/pages/ErrorUnhandled.tsx

@@ -0,0 +1,14 @@
+export type ErrorResponse = {
+  status: number;
+  statusText: string;
+  data: any;
+};
+export function ErrorUnhandled({ error }: { error: ErrorResponse }) {
+  return (
+    <>
+      <h1>Unexpected Error Occurred</h1>
+      <p>Status: {error.status}</p>
+      <p>{error.data.message}</p>
+    </>
+  );
+}

package/src/pages/Root.tsx

@@ -1,7 +1,13 @@
 import type { SiteManifest } from 'myst-config';
 import type { SiteLoader } from '@myst-theme/common';
-import type { NodeRenderer } from '@myst-theme/providers';
-import { BaseUrlProvider, SiteProvider, Theme, ThemeProvider } from '@myst-theme/providers';
+import type { NodeRenderers } from '@myst-theme/providers';
+import {
+  BaseUrlProvider,
+  SiteProvider,
+  Theme,
+  ThemeProvider,
+  useThemeSwitcher,
+} from '@myst-theme/providers';
 import {
   Links,
   LiveReload,
@@ -12,16 +18,24 @@ import {
   useLoaderData,
   Link,
   NavLink,
+  useRouteError,
+  isRouteErrorResponse,
 } from '@remix-run/react';
-import { DEFAULT_NAV_HEIGHT, renderers as defaultRenderers } from '../components/index.js';
+import {
+  DEFAULT_NAV_HEIGHT,
+  renderers as defaultRenderers,
+  BlockingThemeLoader,
+} from '../components/index.js';
+import { useTheme } from '../hooks/index.js';
 import { Analytics } from '../seo/index.js';
 import { Error404 } from './Error404.js';
+import { ErrorUnhandled } from './ErrorUnhandled.js';
 import classNames from 'classnames';
 
 export function Document({
   children,
   scripts,
-  theme,
+  theme: ssrTheme,
   config,
   title,
   staticBuild,
@@ -31,13 +45,13 @@ export function Document({
 }: {
   children: React.ReactNode;
   scripts?: React.ReactNode;
-  theme: Theme;
+  theme?: Theme;
   config?: SiteManifest;
   title?: string;
   staticBuild?: boolean;
   baseurl?: string;
   top?: number;
-  renderers?: Record<string, NodeRenderer>;
+  renderers?: NodeRenderers;
 }) {
   const links = staticBuild
     ? {
@@ -49,7 +63,62 @@ export function Document({
         NavLink: NavLink as any,
       };
 
+  // (Local) theme state driven by SSR and cookie/localStorage
+  const [theme, setTheme] = useTheme({ ssrTheme: ssrTheme, useLocalStorage: staticBuild });
+
+  // Inject blocking element to set proper pre-hydration state
+  const head = ssrTheme ? undefined : <BlockingThemeLoader useLocalStorage={!!staticBuild} />;
+
+  return (
+    <ThemeProvider theme={theme} setTheme={setTheme} renderers={renderers} {...links} top={top}>
+      <DocumentWithoutProviders
+        children={children}
+        scripts={scripts}
+        head={head}
+        config={config}
+        title={title}
+        liveReloadListener={!staticBuild}
+        baseurl={baseurl}
+        top={top}
+      />
+    </ThemeProvider>
+  );
+}
+
+export function DocumentWithoutProviders({
+  children,
+  scripts,
+  head,
+  config,
+  title,
+  baseurl,
+  top = DEFAULT_NAV_HEIGHT,
+  liveReloadListener,
+}: {
+  children: React.ReactNode;
+  scripts?: React.ReactNode;
+  head?: React.ReactNode;
+  config?: SiteManifest;
+  title?: string;
+  baseurl?: string;
+  useLocalStorageForDarkMode?: boolean;
+  top?: number;
+  theme?: Theme;
+  liveReloadListener?: boolean;
+}) {
+  // Theme value from theme context. For a clean page load (no cookies), both ssrTheme and theme are null
+  // And thus the BlockingThemeLoader is used to inject the client-preferred theme (localStorage or media query)
+  // without a FOUC.
+  //
+  // In live-server contexts, setting the theme or changing the system preferred theme will modify the ssrTheme upon next request _and_ update the useThemeSwitcher context state, leading to a re-render
+  // Upon re-render, the state-theme value is set on `html` and the client-side BlockingThemeLoader discovers that it has no additional work to do, exiting the script tag early
+  // Upon a new request to the server, the theme preference is received from the set cookie, and therefore we don't inject a BlockingThemeLoader AND we have the theme value in useThemeSwitcher.
+  //
+  // In static sites, ssrTheme is forever null.
+  // if (ssrTheme) { assert(theme === ssrTheme) }
+  const { theme } = useThemeSwitcher();
   return (
+    // Set the theme during SSR if possible, otherwise leave it up to the BlockingThemeLoader
     <html lang="en" className={classNames(theme)} style={{ scrollPadding: top }}>
       <head>
         <meta charSet="utf-8" />
@@ -61,16 +130,15 @@ export function Document({
           analytics_google={config?.options?.analytics_google}
           analytics_plausible={config?.options?.analytics_plausible}
         />
+        {head}
       </head>
       <body className="m-0 transition-colors duration-500 bg-white dark:bg-stone-900">
-        <ThemeProvider theme={theme} renderers={renderers} {...links} top={top}>
-          <BaseUrlProvider baseurl={baseurl}>
-            <SiteProvider config={config}>{children}</SiteProvider>
-          </BaseUrlProvider>
-        </ThemeProvider>
+        <BaseUrlProvider baseurl={baseurl}>
+          <SiteProvider config={config}>{children}</SiteProvider>
+        </BaseUrlProvider>
         <ScrollRestoration />
         <Scripts />
-        {!staticBuild && <LiveReload />}
+        {liveReloadListener && <LiveReload />}
         {scripts}
       </body>
     </html>
@@ -86,12 +154,13 @@ export function App() {
   );
 }
 
-export function AppCatchBoundary() {
+export function AppErrorBoundary() {
+  const error = useRouteError();
   return (
     <Document theme={Theme.light}>
       <article className="article">
         <main className="article-grid subgrid-gap col-screen">
-          <Error404 />
+          {isRouteErrorResponse(error) ? <Error404 /> : <ErrorUnhandled error={error as any} />}
         </main>
       </article>
     </Document>

package/src/pages/index.ts

@@ -1,5 +1,6 @@
 export { ErrorProjectNotFound } from './ErrorProjectNotFound.js';
 export { ErrorDocumentNotFound } from './ErrorDocumentNotFound.js';
 export { Error404 } from './Error404.js';
-export { ArticlePage, ArticlePageCatchBoundary, ProjectPageCatchBoundary } from './Article.js';
-export { App, Document, AppCatchBoundary } from './Root.js';
+export { ErrorUnhandled } from './ErrorUnhandled.js';
+export { ArticlePage } from './Article.js';
+export { App, Document, AppErrorBoundary } from './Root.js';

package/src/seo/meta.ts

@@ -1,4 +1,4 @@
-import type { HtmlMetaDescriptor, V2_MetaDescriptor } from '@remix-run/react';
+import type { V2_MetaDescriptor } from '@remix-run/react';
 
 export type SocialSite = {
   title: string;
@@ -17,15 +17,15 @@ export type SocialArticle = {
   keywords?: string[];
 };
 
-function allDefined(meta: Record<string, string | null | undefined>): HtmlMetaDescriptor {
-  return Object.fromEntries(Object.entries(meta).filter(([, v]) => v)) as HtmlMetaDescriptor;
+function allDefined(meta: Record<string, string | null | undefined>): V2_MetaDescriptor {
+  return Object.fromEntries(Object.entries(meta).filter(([, v]) => v)) as V2_MetaDescriptor;
 }
 
 export function getMetaTagsForSite_V1({
   title,
   description,
   twitter,
-}: SocialSite): HtmlMetaDescriptor {
+}: SocialSite): V2_MetaDescriptor {
   const meta = {
     title,
     description,
@@ -60,7 +60,7 @@ export function getMetaTagsForArticle_V1({
   image,
   twitter,
   keywords,
-}: SocialArticle): HtmlMetaDescriptor {
+}: SocialArticle): V2_MetaDescriptor {
   const meta = {
     title,
     description,