@myst-theme/site 1.1.1 → 1.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myst-theme/site",
-  "version": "1.1.1",
+  "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.1",
-    "@myst-theme/diagrams": "^1.1.1",
-    "@myst-theme/frontmatter": "^1.1.1",
-    "@myst-theme/providers": "^1.1.1",
-    "@myst-theme/search": "^1.1.1",
+    "@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.1",
+    "myst-demo": "^1.1.2",
     "myst-spec-ext": "^1.8.1",
-    "myst-to-react": "^1.1.1",
+    "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

@@ -19,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;
@@ -160,7 +175,7 @@ const useIntersectionObserver = (elements: Element[], options?: Record<string, a
           if (e.isIntersecting) next.add(e.target);
           else next.delete(e.target);
         });
-        return Array.from(next);
+        return arrayIfChanged(prev, Array.from(next));
       });
     };
     const o = new IntersectionObserver(cb, options ?? {});
@@ -208,7 +223,7 @@ export function useHeaders(selector: string, maxdepth: number) {
   const onMutation = useCallback(
     throttle(
       () => {
-        setElements(getHeaders(selector));
+        setElements((prev) => arrayIfChanged(prev, getHeaders(selector)));
       },
       500,
       // Trailing updates help ensure we eventually process the last DOM mutation burst.
@@ -369,7 +384,7 @@ function useMarginOccluder() {
           .flat()
           .join(', ');
         const marginElements = mainElementRef.current.querySelectorAll(selector);
-        setElements(Array.from(marginElements));
+        setElements((prev) => arrayIfChanged(prev, Array.from(marginElements)));
       },
       500,
       // Trailing updates help ensure we eventually process the last DOM mutation burst.

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

@@ -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>