@myst-theme/site 1.0.1 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myst-theme/site",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "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.0.1",
-    "@myst-theme/diagrams": "^1.0.1",
-    "@myst-theme/frontmatter": "^1.0.1",
-    "@myst-theme/providers": "^1.0.1",
-    "@myst-theme/search": "^1.0.1",
+    "@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",
     "@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.0.1",
+    "myst-demo": "^1.1.1",
     "myst-spec-ext": "^1.8.1",
-    "myst-to-react": "^1.0.1",
+    "myst-to-react": "^1.1.1",
     "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';
@@ -148,13 +149,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 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 +175,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 +195,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);
@@ -192,7 +211,8 @@ export function useHeaders(selector: string, maxdepth: number) {
         setElements(getHeaders(selector));
       },
       500,
-      { trailing: false },
+      // Trailing updates help ensure we eventually process the last DOM mutation burst.
+      { trailing: true },
     ),
     [selector],
   );
@@ -210,6 +230,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 +241,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 +332,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);
@@ -330,7 +372,8 @@ function useMarginOccluder() {
         setElements(Array.from(marginElements));
       },
       500,
-      { trailing: false },
+      // Trailing updates help ensure we eventually process the last DOM mutation burst.
+      { trailing: true },
     ),
     [],
   );
@@ -343,7 +386,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 +444,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/Link.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { useLinkProvider, useNavLinkProvider } from '@myst-theme/providers';
+import { isExternalUrl, useLinkProvider, useNavLinkProvider } from '@myst-theme/providers';
 
 export function ExternalOrInternalLink({
   to,
@@ -19,7 +19,7 @@ export function ExternalOrInternalLink({
   const Link = useLinkProvider();
   const NavLink = useNavLinkProvider();
   const staticClass = typeof className === 'function' ? className({ isActive: false }) : className;
-  if (to.startsWith('http') || to.startsWith('mailto:')) {
+  if (isExternalUrl(to)) {
     return (
       <a
         href={to}

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',
         {

package/src/components/Navigation/TableOfContentsItems.tsx

@@ -172,7 +172,7 @@ const NestedToc = ({ heading }: { heading: NestedHeading }) => {
     <Collapsible.Root className="w-full" open={open} onOpenChange={setOpen}>
       <div
         className={classNames(
-          'myst-toc-item flex flex-row w-full gap-2 px-2 my-1 text-left rounded-lg outline-none',
+          'myst-toc-item flex flex-row w-full gap-2 pl-2 my-1 text-left rounded-lg outline-none',
           {
             'myst-toc-item-exact bg-blue-300/30': exact,
             'hover:bg-slate-300/30': !exact,
@@ -189,7 +189,7 @@ const NestedToc = ({ heading }: { heading: NestedHeading }) => {
         />
         <Collapsible.Trigger asChild>
           <button
-            className="self-center flex-none rounded-md group hover:bg-slate-300/30 focus:outline outline-blue-200 outline-2"
+            className="self-stretch flex items-center flex-none px-1 rounded-l-md group hover:bg-slate-300/30 focus-visible:outline outline-blue-200 outline-2"
             aria-label="Open Folder"
           >
             <ChevronRightIcon