@myst-theme/site 1.1.0 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myst-theme/site",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -25,11 +25,11 @@
   "dependencies": {
     "@headlessui/react": "^1.7.15",
     "@heroicons/react": "^2.0.18",
-    "@myst-theme/common": "^1.1.0",
-    "@myst-theme/diagrams": "^1.1.0",
-    "@myst-theme/frontmatter": "^1.1.0",
-    "@myst-theme/providers": "^1.1.0",
-    "@myst-theme/search": "^1.1.0",
+    "@myst-theme/common": "^1.1.2",
+    "@myst-theme/diagrams": "^1.1.2",
+    "@myst-theme/frontmatter": "^1.1.2",
+    "@myst-theme/providers": "^1.1.2",
+    "@myst-theme/search": "^1.1.2",
     "@radix-ui/react-collapsible": "^1.0.3",
     "@radix-ui/react-dialog": "^1.0.3",
     "@radix-ui/react-visually-hidden": "^1.1.0",
@@ -37,9 +37,9 @@
     "lodash.throttle": "^4.1.1",
     "myst-common": "^1.8.1",
     "myst-config": "^1.7.9",
-    "myst-demo": "^1.1.0",
+    "myst-demo": "^1.1.2",
     "myst-spec-ext": "^1.8.1",
-    "myst-to-react": "^1.1.0",
+    "myst-to-react": "^1.1.2",
     "nbtx": "^0.2.3",
     "node-cache": "^5.1.2",
     "node-fetch": "^2.6.11",

package/src/components/DocumentOutline.tsx

@@ -2,12 +2,13 @@ import {
   useBaseurl,
   useNavLinkProvider,
   useSiteManifest,
+  useThemeTop,
   withBaseurl,
 } from '@myst-theme/providers';
 import { useNavigation } from '@remix-run/react';
 import classNames from 'classnames';
 import throttle from 'lodash.throttle';
-import React, { useCallback, useEffect, useRef, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import type { RefObject } from 'react';
 import { DocumentChartBarIcon } from '@heroicons/react/24/outline';
 import { ChevronRightIcon } from '@heroicons/react/24/solid';
@@ -18,6 +19,21 @@ const SELECTOR = [1, 2, 3, 4].map((n) => `main h${n}`).join(', ');
 
 const onClient = typeof document !== 'undefined';
 
+/**
+ * Returns `next` if it differs from `prev`, otherwise returns `prev` unchanged.
+ * This prevents unnecessary React state updates (and re-renders) when the
+ * array contents haven't actually changed - important for breaking feedback
+ * loops with IntersectionObserver and MutationObserver.
+ */
+function arrayIfChanged<T>(prev: T[], next: T[]): T[] {
+  if (prev === next) return prev;
+  if (prev.length !== next.length) return next;
+  for (let i = 0; i < prev.length; i++) {
+    if (prev[i] !== next[i]) return next;
+  }
+  return prev;
+}
+
 export type Heading = {
   element: HTMLHeadingElement;
   id: string;
@@ -148,13 +164,24 @@ const useIntersectionObserver = (elements: Element[], options?: Record<string, a
 
   if (!onClient) return { observer };
   useEffect(() => {
+    // We want a list of all header elements on screen to loop through, but:
+    // IntersectionObserver returns elements that have *changed state*, not the full list of elements on screen.
+    // So we maintain a set of on-screen elements and add/remove as new intersection events happen.
     const cb: IntersectionObserverCallback = (entries) => {
-      setIntersecting(entries.filter((e) => e.isIntersecting).map((e) => e.target));
+      setIntersecting((prev) => {
+        const next = new Set(prev);
+        // Add or remove from our set based on intersection state
+        entries.forEach((e) => {
+          if (e.isIntersecting) next.add(e.target);
+          else next.delete(e.target);
+        });
+        return arrayIfChanged(prev, Array.from(next));
+      });
     };
     const o = new IntersectionObserver(cb, options ?? {});
     setObserver(o);
     return () => o.disconnect();
-  }, []);
+  }, [options]);
 
   // Changes to the DOM mean we need to update our intersection observer
   useEffect(() => {
@@ -163,12 +190,18 @@ const useIntersectionObserver = (elements: Element[], options?: Record<string, a
     }
     // Observe all heading elements
     const toWatch = elements;
-    toWatch.map((e) => observer.observe(e));
+    toWatch.forEach((e) => {
+      observer.observe(e);
+    });
     // Cleanup afterwards
     return () => {
-      toWatch.map((e) => observer.unobserve(e));
+      toWatch.forEach((e) => {
+        observer.unobserve(e);
+      });
+      // Ensure we don't keep stale references when elements are removed/unobserved.
+      setIntersecting((prev) => prev.filter((e) => !toWatch.includes(e)));
     };
-  }, [elements]);
+  }, [elements, observer]);
 
   return { observer, intersecting };
 };
@@ -177,6 +210,7 @@ const useIntersectionObserver = (elements: Element[], options?: Record<string, a
  * Keep track of which headers are visible, and which header is active
  */
 export function useHeaders(selector: string, maxdepth: number) {
+  const topOffset = useThemeTop();
   if (!onClient) return { activeId: '', headings: [] };
   // Keep track of main manually for now
   const mainElementRef = useRef<HTMLElement | null>(null);
@@ -189,10 +223,11 @@ export function useHeaders(selector: string, maxdepth: number) {
   const onMutation = useCallback(
     throttle(
       () => {
-        setElements(getHeaders(selector));
+        setElements((prev) => arrayIfChanged(prev, getHeaders(selector)));
       },
       500,
-      { trailing: false },
+      // Trailing updates help ensure we eventually process the last DOM mutation burst.
+      { trailing: true },
     ),
     [selector],
   );
@@ -210,6 +245,9 @@ export function useHeaders(selector: string, maxdepth: number) {
   const [activeId, setActiveId] = useState<string>();
 
   useEffect(() => {
+    // Use the theme's top offset (navbar height) + a bit of padding for filtering active headings to avoid over-shooting the header.
+    const OFFSET_PX = topOffset - 10;
+    // Prefer a heading marked as highlighted (e.g. focus/anchor) if one is currently intersecting.
     const highlighted = intersecting!.reduce(
       (a, b) => {
         if (a) return a;
@@ -218,11 +256,28 @@ export function useHeaders(selector: string, maxdepth: number) {
       },
       null as string | null,
     );
-    const active = [...(intersecting as HTMLElement[])].sort(
-      (a, b) => a.offsetTop - b.offsetTop,
-    )[0];
-    if (highlighted || active) setActiveId(highlighted || active.id);
-  }, [intersecting]);
+    const intersectingElements = intersecting as HTMLElement[];
+    // Choose the heading closest to the navbar offset line within a viewport window under it.
+    // Using a window avoids a case where the active header is off screen the next header is way at the bottom of the screen.
+    let bestInActiveHeaderWindow: { el: HTMLElement; distance: number } | undefined;
+    const ACTIVE_WINDOW_PX = window.innerHeight * 0.33;
+    for (const el of intersectingElements) {
+      const distance = el.getBoundingClientRect().top - OFFSET_PX;
+      if (
+        // Only keep things under the navbar line
+        distance >= 0 &&
+        // Only keep things over the active window size
+        distance <= ACTIVE_WINDOW_PX &&
+        // Now if it's closer to the navbar line than the active element, update active
+        (!bestInActiveHeaderWindow || distance < bestInActiveHeaderWindow.distance)
+      ) {
+        bestInActiveHeaderWindow = { el, distance };
+      }
+    }
+    // If nothing is below the navbar line, keep the current active heading.
+    const active = bestInActiveHeaderWindow?.el;
+    if (highlighted || active) setActiveId(highlighted || active?.id);
+  }, [intersecting, topOffset]);
 
   const [headings, setHeadings] = useState<Heading[]>([]);
   useEffect(() => {
@@ -292,6 +347,8 @@ export function useOutlineHeight<T extends HTMLElement = HTMLElement>(
 function useMarginOccluder() {
   const [occluded, setOccluded] = useState(false);
   const [elements, setElements] = useState<Element[]>([]);
+  // Memoize options so `useIntersectionObserver(..., options)` doesn't recreate the observer each render.
+  const intersectionOptions = useMemo(() => ({ rootMargin: '0px 0px -33% 0px' }), []);
 
   // Keep track of main manually for now
   const mainElementRef = useRef<HTMLElement | null>(null);
@@ -327,10 +384,11 @@ function useMarginOccluder() {
           .flat()
           .join(', ');
         const marginElements = mainElementRef.current.querySelectorAll(selector);
-        setElements(Array.from(marginElements));
+        setElements((prev) => arrayIfChanged(prev, Array.from(marginElements)));
       },
       500,
-      { trailing: false },
+      // Trailing updates help ensure we eventually process the last DOM mutation burst.
+      { trailing: true },
     ),
     [],
   );
@@ -343,7 +401,7 @@ function useMarginOccluder() {
   // Trigger initial update
   useEffect(onMutation, []);
   // Keep tabs of margin elements on screen
-  const { intersecting } = useIntersectionObserver(elements, { rootMargin: '0px 0px -33% 0px' });
+  const { intersecting } = useIntersectionObserver(elements, intersectionOptions);
   useEffect(() => {
     setOccluded(intersecting!.length > 0);
   }, [intersecting]);
@@ -401,6 +459,7 @@ export const DocumentOutline = ({
         className={classNames(
           'myst-outline not-prose overflow-y-auto',
           'transition-opacity duration-700', // Animation on load
+          'bg-white/95 dark:bg-stone-900/95 backdrop-blur-sm rounded-lg p-2 -m-2', // Solid background to avoid overlap with margin content
           className,
         )}
         style={{

package/src/components/Navigation/HomeLink.tsx

@@ -5,18 +5,21 @@ export function HomeLink({
   logo,
   logoDark,
   logoText,
+  logoAlt,
   name,
   url,
 }: {
   logo?: string;
   logoDark?: string;
   logoText?: string;
+  logoAlt?: string;
   name?: string;
   url?: string;
 }) {
   const Link = useLinkProvider();
   const baseurl = useBaseurl();
   const nothingSet = !logo && !logoText;
+  const altText = logoAlt ?? logoText ?? name;
   return (
     <Link
       className="myst-home-link flex items-center ml-3 dark:text-white w-fit md:ml-5 xl:ml-7"
@@ -32,14 +35,14 @@ export function HomeLink({
           <img
             src={logo}
             className={classNames('h-9', { 'dark:hidden': !!logoDark })}
-            alt={logoText || name}
+            alt={altText}
             height="2.25rem"
           ></img>
           {logoDark && (
             <img
               src={logoDark}
               className="hidden h-9 dark:block"
-              alt={logoText || name}
+              alt={altText}
               height="2.25rem"
             ></img>
           )}

package/src/components/Navigation/Loading.tsx

@@ -48,7 +48,7 @@ export function LoadingBar() {
   return (
     <div
       className={classNames(
-        'myst-loading-bar w-screen h-[2px] bg-blue-500 absolute left-0 bottom-0 transition-transform',
+        'myst-loading-bar w-full h-[2px] bg-blue-500 absolute left-0 bottom-0 transition-transform',
         {
           'myst-loading-bar-progress animate-load scale-x-40': isLoading,
           'scale-x-100': !isLoading,

package/src/components/Navigation/Navigation.tsx

@@ -91,13 +91,18 @@ export const ConfigurablePrimaryNavigation = ({
   return (
     <>
       {open && !mobileOnly && headings && (
+        // Darkened backdrop behind the open sidebar on mobile.
         <div
-          className="myst-navigation-overlay fixed inset-0 z-30 bg-black opacity-50"
+          // It follows the same top-offset rules as the sidebar: header offset on desktop,
+          // full-screen from top on mobile.
+          className="myst-navigation-overlay fixed inset-0 max-xl:z-40 xl:z-30 bg-black opacity-50 max-xl:!mt-0"
           style={{ marginTop: top }}
+          // Clicking the backdrop is the primary escape path for closing the sidebar.
           onClick={() => setOpen(false)}
         ></div>
       )}
       <PrimarySidebar
+        // The actual sidebar panel is here; the overlay backdrop is above.
         sidebarRef={sidebarRef}
         nav={nav}
         headings={headings}

package/src/components/Navigation/PrimarySidebar.tsx

@@ -99,24 +99,38 @@ export function SidebarNav({ nav }: { nav?: SiteManifest['nav'] }) {
   );
 }
 
+/**
+ * Manages the sidebar's position and height on scroll.
+ *
+ * On wide screen, the sidebar is position:fixed and needs JS to
+ *  grow/shrink/move based on other elements as we scroll
+ *
+ * On non-wide, the sidebar is a full-screen overlay — CSS handles everything.
+ */
 export function useSidebarHeight<T extends HTMLElement = HTMLElement>(top = 0, inset = 0) {
   const container = useRef<T>(null);
   const toc = useRef<HTMLDivElement>(null);
   const transitionState = useNavigation().state;
   const wide = useIsWide();
   const { bannerState } = useBannerState();
-  const totalTop = top + bannerState.height;
-
   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 - ${totalTop}px), ${height + inset}px)`
-        : `calc(100vh - ${totalTop}px)`;
-    if (div) div.style.height = `min(calc(100vh - ${totalTop}px), ${height + inset}px)`;
     const nav = toc.current.querySelector('nav');
+    if (!wide) {
+      // On mobile, clear any stale inline styles so CSS can handle sizing.
+      if (div) div.style.height = '';
+      if (nav) nav.style.opacity = '';
+      return;
+    }
+    // As the banner scrolls out of view, slide the sidebar up to stay
+    // just below the sticky TopNav.
+    const effectiveBannerHeight = Math.max(0, bannerState.height - window.scrollY);
+    const effectiveTop = top + effectiveBannerHeight;
+    toc.current.style.top = `${effectiveTop}px`;
+    // Sidebar height: fill the viewport but don't extend past the article.
+    const height = Math.max(0, container.current.offsetHeight - window.scrollY);
+    if (div) div.style.height = `min(calc(100vh - ${effectiveTop}px), ${height + inset}px)`;
     if (nav) nav.style.opacity = height > 150 ? '1' : '0';
   };
   useEffect(() => {
@@ -127,7 +141,7 @@ export function useSidebarHeight<T extends HTMLElement = HTMLElement>(top = 0, i
     return () => {
       window.removeEventListener('scroll', handleScroll);
     };
-  }, [container, toc, transitionState, wide, totalTop]);
+  }, [container, toc, transitionState, wide, top, bannerState.height]);
   return { container, toc };
 }
 
@@ -152,6 +166,8 @@ export const PrimarySidebar = ({
   const footerRef = useRef<HTMLDivElement>(null);
   const [open] = useNavOpen();
   const config = useSiteManifest();
+  // Applies layout and whitespacing to a few sidebar sections
+  const sidebarSectionInsetClass = 'ml-3 xl:ml-0 mr-3 max-w-[350px]';
 
   useEffect(() => {
     setTimeout(() => {
@@ -169,9 +185,13 @@ export const PrimarySidebar = ({
         'myst-primary-sidebar',
         'fixed',
         `xl:${grid}`, // for example, xl:article-grid
-        'grid-gap xl:w-screen xl:pointer-events-none overflow-auto max-xl:min-w-[300px]',
+        // Base sidebar layout and scrolling behavior
+        'grid-gap xl:w-full xl:pointer-events-none overflow-auto',
+        // Mobile modal behavior: cap width, pin to top, and fill viewport height
+        'max-xl:w-[75vw] max-xl:max-w-[350px] max-xl:!top-0 max-xl:h-screen',
         { 'lg:hidden': nav && hide_toc },
-        { hidden: !open, 'z-30': open, 'z-10': !open },
+        // raise sidebar above content when open
+        { hidden: !open, 'max-xl:z-40 xl:z-30': open, 'z-10': !open },
       )}
       style={{ top: top + bannerState.height }}
     >
@@ -180,7 +200,7 @@ export const PrimarySidebar = ({
           'myst-primary-sidebar-pointer',
           'pointer-events-auto',
           'xl:col-margin-left flex-col',
-          'overflow-hidden',
+          'overflow-hidden max-xl:h-full',
           {
             flex: open,
             'bg-white dark:bg-stone-900': open, // just apply when open, so that theme can transition
@@ -194,7 +214,10 @@ export const PrimarySidebar = ({
           {nav && (
             <nav
               aria-label="Navigation"
-              className="myst-primary-sidebar-topnav overflow-y-hidden transition-opacity ml-3 xl:ml-0 mr-3 max-w-[350px] lg:hidden"
+              className={classNames(
+                'myst-primary-sidebar-topnav overflow-y-hidden transition-opacity lg:hidden',
+                sidebarSectionInsetClass,
+              )}
             >
               <SidebarNav nav={nav} />
             </nav>
@@ -203,7 +226,10 @@ export const PrimarySidebar = ({
           {headings && (
             <nav
               aria-label="Table of Contents"
-              className="myst-primary-sidebar-toc flex-grow overflow-y-hidden transition-opacity ml-3 xl:ml-0 mr-3 max-w-[350px]"
+              className={classNames(
+                'myst-primary-sidebar-toc flex-grow overflow-y-hidden transition-opacity',
+                sidebarSectionInsetClass,
+              )}
             >
               <Toc headings={headings} />
             </nav>
@@ -211,7 +237,10 @@ export const PrimarySidebar = ({
         </div>
         {footer && (
           <div
-            className="myst-primary-sidebar-footer flex-none py-6 transition-all duration-700 translate-y-6 opacity-0"
+            className={classNames(
+              'myst-primary-sidebar-footer flex-none py-6 transition-all duration-700 translate-y-6 opacity-0',
+              sidebarSectionInsetClass,
+            )}
             ref={footerRef}
           >
             {footer}

package/src/components/Navigation/Search.tsx

@@ -174,7 +174,7 @@ function SearchShortcut() {
   return (
     <div
       aria-hidden
-      className="myst-search-shortcut items-center hidden mx-1 font-mono text-sm text-gray-600 sm:flex gap-x-1"
+      className="myst-search-shortcut items-center hidden mx-1 font-mono text-sm text-gray-600 dark:text-gray-300 sm:flex gap-x-1"
     >
       <kbd
         className={classNames(
@@ -507,7 +507,7 @@ function SearchForm({
       <form onSubmit={onSubmit}>
         <div className="relative flex w-full h-10 flow-row gap-x-1 ">
           <label id={searchLabelID} htmlFor={searchInputID}>
-            <MagnifyingGlassIcon className="absolute text-gray-600 inset-y-0 start-0 h-10 w-10 p-2.5 aspect-square flex items-center pointer-events-none" />
+            <MagnifyingGlassIcon className="absolute text-gray-600 dark:text-gray-300 inset-y-0 start-0 h-10 w-10 p-2.5 aspect-square flex items-center pointer-events-none" />
             <span className="hidden">Search query</span>
           </label>
           <input
@@ -563,7 +563,7 @@ const SearchPlaceholderButton = forwardRef<
       className={classNames(
         'myst-search-bar',
         className,
-        'flex items-center h-10 aspect-square sm:w-64 text-left text-gray-600',
+        'flex items-center h-10 aspect-square sm:w-64 text-left text-gray-600 dark:text-gray-300',
         'border border-gray-300 dark:border-gray-600',
         'rounded-lg bg-gray-50 dark:bg-gray-700',
         {
@@ -632,7 +632,7 @@ export function Search({ debounceTime = 500, charLimit = 64 }: SearchProps) {
       <Dialog.Portal>
         <Dialog.Overlay className="fixed inset-0 bg-[#656c85cc] z-[1000]" />
         <Dialog.Content
-          className="myst-search-dialog fixed flex flex-col top-0 bg-white dark:bg-stone-900 z-[1001] h-screen w-screen sm:left-1/2 sm:-translate-x-1/2 sm:w-[90vw] sm:max-w-screen-sm sm:h-auto sm:max-h-[var(--content-max-height)] sm:top-[var(--content-top)] sm:rounded-md p-4 text-gray-900 dark:text-white"
+          className="myst-search-dialog fixed flex flex-col top-0 bg-white dark:bg-stone-900 z-[1001] h-screen w-full sm:left-1/2 sm:-translate-x-1/2 sm:w-[90vw] sm:max-w-screen-sm sm:h-auto sm:max-h-[var(--content-max-height)] sm:top-[var(--content-top)] sm:rounded-md p-4 text-gray-900 dark:text-white"
           // Store state as CSS variables so that we can set the style with tailwind variants
           style={
             {

package/src/components/Navigation/TopNav.tsx

@@ -117,9 +117,9 @@ export function TopNav({ hideToc, hideSearch }: { hideToc?: boolean; hideSearch?
   const [open, setOpen] = useNavOpen();
   const config = useSiteManifest();
   const { title, nav, actions } = config ?? {};
-  const { logo, logo_dark, logo_text, logo_url } = config?.options ?? {};
+  const { logo, logo_dark, logo_text, logo_url, logo_alt } = config?.options ?? {};
   return (
-    <div className="myst-top-nav bg-white/80 backdrop-blur dark:bg-stone-900/80 shadow dark:shadow-stone-700 p-3 md:px-8 sticky w-screen top-0 z-30 h-[60px]">
+    <div className="myst-top-nav bg-white/80 backdrop-blur dark:bg-stone-900/80 shadow dark:shadow-stone-700 p-3 md:px-8 sticky w-full top-0 z-30 h-[60px]">
       <nav className="myst-top-nav-bar flex items-center justify-between flex-nowrap max-w-[1440px] mx-auto">
         <div className="flex flex-row xl:min-w-[19.5rem] mr-2 sm:mr-7 justify-start items-center shrink-0">
           {
@@ -145,6 +145,7 @@ export function TopNav({ hideToc, hideSearch }: { hideToc?: boolean; hideSearch?
             logo={logo}
             logoDark={logo_dark}
             logoText={logo_text}
+            logoAlt={logo_alt}
             url={logo_url}
           />
         </div>