@myst-theme/site 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myst-theme/site",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
@@ -21,22 +21,30 @@
   "dependencies": {
     "@headlessui/react": "^1.7.15",
     "@heroicons/react": "^2.0.18",
-    "@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",
+    "@myst-theme/common": "^0.13.0",
+    "@myst-theme/diagrams": "^0.13.0",
+    "@myst-theme/frontmatter": "^0.13.0",
+    "@myst-theme/jupyter": "^0.13.0",
+    "@myst-theme/providers": "^0.13.0",
+    "@myst-theme/search": "^0.13.0",
     "@radix-ui/react-collapsible": "^1.0.3",
+    "@radix-ui/react-dialog": "^1.0.3",
+    "@radix-ui/react-radio-group": "^1.2.0",
+    "@radix-ui/react-roving-focus": "^1.1.0",
+    "@radix-ui/react-slot": "^1.1.0",
+    "@radix-ui/react-visually-hidden": "^1.1.0",
     "classnames": "^2.3.2",
     "lodash.throttle": "^4.1.1",
-    "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",
+    "myst-common": "^1.7.0",
+    "myst-config": "^1.7.0",
+    "myst-demo": "^0.13.0",
+    "myst-spec-ext": "^1.7.0",
+    "myst-to-react": "^0.13.0",
     "nbtx": "^0.2.3",
     "node-cache": "^5.1.2",
     "node-fetch": "^2.6.11",
+    "react-merge-refs": "^2.1.1",
+    "string.prototype.matchall": "^4.0.11",
     "thebe-react": "0.4.10",
     "unist-util-select": "^4.0.1"
   },

package/src/components/DocumentOutline.tsx

@@ -8,10 +8,12 @@ import { useNavigation } from '@remix-run/react';
 import classNames from 'classnames';
 import throttle from 'lodash.throttle';
 import React, { useCallback, useEffect, useRef, useState } from 'react';
+import type { RefObject } from 'react';
 import { DocumentChartBarIcon } from '@heroicons/react/24/outline';
+import { ChevronRightIcon } from '@heroicons/react/24/solid';
+import * as Collapsible from '@radix-ui/react-collapsible';
 
 const SELECTOR = [1, 2, 3, 4].map((n) => `main h${n}`).join(', ');
-const HIGHLIGHT_CLASS = 'highlight';
 
 const onClient = typeof document !== 'undefined';
 
@@ -25,15 +27,13 @@ export type Heading = {
 
 type Props = {
   headings: Heading[];
-  selector: string;
   activeId?: string;
-  highlight?: () => void;
 };
 /**
  * This renders an item in the table of contents list.
  * scrollIntoView is used to ensure that when a user clicks on an item, it will smoothly scroll.
  */
-const Headings = ({ headings, activeId, highlight, selector }: Props) => (
+const Headings = ({ headings, activeId }: Props) => (
   <ul className="text-sm leading-6 text-slate-400">
     {headings.map((heading) => (
       <li
@@ -62,11 +62,7 @@ const Headings = ({ headings, activeId, highlight, selector }: Props) => (
             e.preventDefault();
             const el = document.querySelector(`#${heading.id}`);
             if (!el) return;
-            getHeaders(selector).forEach((h) => {
-              h.classList.remove(HIGHLIGHT_CLASS);
-            });
-            el.classList.add(HIGHLIGHT_CLASS);
-            highlight?.();
+
             el.scrollIntoView({ behavior: 'smooth' });
             history.replaceState(undefined, '', `#${heading.id}`);
           }}
@@ -105,15 +101,111 @@ function getHeaders(selector: string): HTMLHeadingElement[] {
   return headers as HTMLHeadingElement[];
 }
 
+type MutationCallback = (mutations: MutationRecord[], observer: MutationObserver) => void;
+
+function useMutationObserver(
+  targetRef: RefObject<Element>,
+  callback: MutationCallback,
+  options: Record<string, any>,
+) {
+  const [observer, setObserver] = useState<MutationObserver | null>(null);
+
+  if (!onClient) return { observer };
+
+  // Create observer
+  useEffect(() => {
+    const obs = new MutationObserver(callback);
+    setObserver(obs);
+  }, [callback, setObserver]);
+
+  // Setup observer
+  useEffect(() => {
+    if (!observer || !targetRef.current) {
+      return;
+    }
+
+    try {
+      observer.observe(targetRef.current, options);
+    } catch (e) {
+      console.error(e);
+    }
+    return () => {
+      if (observer) {
+        observer.disconnect();
+      }
+    };
+  }, [observer]);
+}
+
+const useIntersectionObserver = (elements: Element[], options?: Record<string, any>) => {
+  const [observer, setObserver] = useState<IntersectionObserver | null>(null);
+  const [intersecting, setIntersecting] = useState<Element[]>([]);
+
+  if (!onClient) return { observer };
+  useEffect(() => {
+    const cb: IntersectionObserverCallback = (entries) => {
+      setIntersecting(entries.filter((e) => e.isIntersecting).map((e) => e.target));
+    };
+    const o = new IntersectionObserver(cb, options ?? {});
+    setObserver(o);
+    return () => o.disconnect();
+  }, []);
+
+  // Changes to the DOM mean we need to update our intersection observer
+  useEffect(() => {
+    if (!observer) {
+      return;
+    }
+    // Observe all heading elements
+    const toWatch = elements;
+    toWatch.map((e) => observer.observe(e));
+    // Cleanup afterwards
+    return () => {
+      toWatch.map((e) => observer.unobserve(e));
+    };
+  }, [elements]);
+
+  return { observer, intersecting };
+};
+
+/**
+ * Keep track of which headers are visible, and which header is active
+ */
 export function useHeaders(selector: string, maxdepth: number) {
   if (!onClient) return { activeId: '', headings: [] };
-  const onScreen = useRef<Set<HTMLHeadingElement>>(new Set());
+  // Keep track of main manually for now
+  const mainElementRef = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    mainElementRef.current = document.querySelector('main');
+  }, []);
+
+  // Track changes to the DOM
+  const [elements, setElements] = useState<HTMLHeadingElement[]>([]);
+  const onMutation = useCallback(
+    throttle(
+      () => {
+        setElements(getHeaders(selector));
+      },
+      500,
+      { trailing: false },
+    ),
+    [selector],
+  );
+  useMutationObserver(mainElementRef, onMutation, {
+    attributes: true,
+    childList: true,
+    subtree: true,
+  });
+
+  // Trigger initial update
+  useEffect(onMutation, []);
+
+  // Watch intersections with headings
+  const { intersecting } = useIntersectionObserver(elements);
   const [activeId, setActiveId] = useState<string>();
-  const headingsSet = useRef<Set<HTMLHeadingElement>>(new Set());
 
-  const highlight = useCallback(() => {
-    const current = [...onScreen.current];
-    const highlighted = current.reduce(
+  useEffect(() => {
+    const highlighted = intersecting!.reduce(
       (a, b) => {
         if (a) return a;
         if (b.classList.contains('highlight')) return b.id;
@@ -121,80 +213,43 @@ export function useHeaders(selector: string, maxdepth: number) {
       },
       null as string | null,
     );
-    const active = [...onScreen.current].sort((a, b) => a.offsetTop - b.offsetTop)[0];
+    const active = [...(intersecting as HTMLElement[])].sort(
+      (a, b) => a.offsetTop - b.offsetTop,
+    )[0];
     if (highlighted || active) setActiveId(highlighted || active.id);
-  }, []);
-
-  const { observer } = useIntersectionObserver(highlight, onScreen.current);
-  const [elements, setElements] = useState<HTMLHeadingElement[]>([]);
+  }, [intersecting]);
 
-  const render = throttle(() => setElements(getHeaders(selector)), 500);
+  const [headings, setHeadings] = useState<Heading[]>([]);
   useEffect(() => {
-    // We have to look at the document changes for reloads/mutations
-    const main = document.querySelector('main');
-    const mutations = new MutationObserver(render);
-    // Fire when added to the dom
-    render();
-    if (main) {
-      mutations.observe(main, { attributes: true, childList: true, subtree: true });
-    }
-    return () => mutations.disconnect();
-  }, []);
-
-  useEffect(() => {
-    // Re-observe all elements when the observer changes
-    Array.from(elements).map((e) => observer.current?.observe(e));
-  }, [observer]);
+    let minLevel = 10;
+    const thisHeadings: Heading[] = elements
+      .map((element) => {
+        return {
+          element,
+          level: Number(element.tagName.slice(1)),
+          id: element.id,
+          text: element.querySelector('.heading-text'),
+        };
+      })
+      .filter((h) => !!h.text)
+      .map(({ element, level, text, id }) => {
+        const { innerText: title, innerHTML: titleHTML } = cloneHeadingElement(
+          text as HTMLSpanElement,
+        );
+        minLevel = Math.min(minLevel, level);
+        return { element, title, titleHTML, id, level };
+      })
+      .filter((heading) => {
+        heading.level = heading.level - minLevel + 1;
+        return heading.level < maxdepth + 1;
+      });
 
-  let minLevel = 10;
-  const headings: Heading[] = elements
-    .map((element) => {
-      return {
-        element,
-        level: Number(element.tagName.slice(1)),
-        id: element.id,
-        text: element.querySelector('.heading-text'),
-      };
-    })
-    .filter((h) => !!h.text)
-    .map(({ element, level, text, id }) => {
-      const { innerText: title, innerHTML: titleHTML } = cloneHeadingElement(
-        text as HTMLSpanElement,
-      );
-      minLevel = Math.min(minLevel, level);
-      return { element, title, titleHTML, id, level };
-    })
-    .filter((heading) => {
-      heading.level = heading.level - minLevel + 1;
-      return heading.level < maxdepth + 1;
-    });
-
-  headings.forEach(({ element: e }) => {
-    if (headingsSet.current.has(e)) return;
-    observer.current?.observe(e);
-    headingsSet.current.add(e);
-  });
+    setHeadings(thisHeadings);
+  }, [elements]);
 
-  return { activeId, highlight, headings };
+  return { activeId, headings };
 }
 
-const useIntersectionObserver = (highlight: () => void, onScreen: Set<HTMLHeadingElement>) => {
-  const observer = useRef<IntersectionObserver | null>(null);
-  if (!onClient) return { observer };
-  useEffect(() => {
-    const callback: IntersectionObserverCallback = (entries) => {
-      entries.forEach((entry) => {
-        onScreen[entry.isIntersecting ? 'add' : 'delete'](entry.target as HTMLHeadingElement);
-      });
-      highlight();
-    };
-    const o = new IntersectionObserver(callback);
-    observer.current = o;
-    return () => o.disconnect();
-  }, [highlight, onScreen]);
-  return { observer };
-};
-
 export function useOutlineHeight<T extends HTMLElement = HTMLElement>(
   existingContainer?: React.RefObject<T>,
 ) {
@@ -226,6 +281,71 @@ export function useOutlineHeight<T extends HTMLElement = HTMLElement>(
   return { container, outline };
 }
 
+/**
+ * Determine whether the margin outline should be occluded by margin elements
+ */
+function useMarginOccluder() {
+  const [occluded, setOccluded] = useState(false);
+  const [elements, setElements] = useState<Element[]>([]);
+
+  // Keep track of main manually for now
+  const mainElementRef = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    mainElementRef.current = document.querySelector('main');
+  }, []);
+
+  // Update list of margin elements
+  const onMutation = useCallback(
+    throttle(
+      () => {
+        if (!mainElementRef.current) {
+          return;
+        }
+        // Watch margin elements, or their direct descendents (as some margin elements have height set to zero)
+        const classes = [
+          'col-margin-right',
+          'col-margin-right-inset',
+          'col-gutter-outset-right',
+          'col-screen-right',
+          'col-screen-inset-right',
+          'col-page-right',
+          'col-page-inset-right',
+          'col-body-outset-right',
+          'col-gutter-page-right',
+          // 'col-screen', // This is on everything!
+          'col-page',
+          'col-page-inset',
+          'col-body-outset',
+        ];
+        const selector = classes
+          .map((cls) => [`.${cls}`, `.${cls} > *`])
+          .flat()
+          .join(', ');
+        const marginElements = mainElementRef.current.querySelectorAll(selector);
+        setElements(Array.from(marginElements));
+      },
+      500,
+      { trailing: false },
+    ),
+    [],
+  );
+  useMutationObserver(mainElementRef, onMutation, {
+    attributes: true,
+    childList: true,
+    subtree: true,
+  });
+
+  // Trigger initial update
+  useEffect(onMutation, []);
+  // Keep tabs of margin elements on screen
+  const { intersecting } = useIntersectionObserver(elements, { rootMargin: '0px 0px -33% 0px' });
+  useEffect(() => {
+    setOccluded(intersecting!.length > 0);
+  }, [intersecting]);
+
+  return { occluded };
+}
+
 export const DocumentOutline = ({
   outlineRef,
   top = 0,
@@ -233,6 +353,7 @@ export const DocumentOutline = ({
   selector = SELECTOR,
   children,
   maxdepth = 4,
+  isMargin,
 }: {
   outlineRef?: React.RefObject<HTMLElement>;
   top?: number;
@@ -241,31 +362,63 @@ export const DocumentOutline = ({
   selector?: string;
   children?: React.ReactNode;
   maxdepth?: number;
+  isMargin: boolean;
 }) => {
-  const { activeId, headings, highlight } = useHeaders(selector, maxdepth);
+  const { activeId, headings } = useHeaders(selector, maxdepth);
+  const [open, setOpen] = useState(false);
+
+  // Keep track of changing occlusion
+  const { occluded } = useMarginOccluder();
+
+  // Handle transition between margin and non-margin
+  useEffect(() => {
+    setOpen(true);
+  }, [isMargin]);
+
+  // Handle occlusion when outline is in margin
+  useEffect(() => {
+    if (isMargin) {
+      setOpen(!occluded);
+    }
+  }, [occluded, isMargin]);
+
   if (headings.length <= 1 || !onClient) {
     return <nav suppressHydrationWarning>{children}</nav>;
   }
+
   return (
-    <nav
-      ref={outlineRef}
-      aria-label="Document Outline"
-      className={classNames(
-        'not-prose overflow-y-auto',
-        'transition-opacity duration-700', // Animation on load
-        className,
-      )}
-      style={{
-        top: top,
-        maxHeight: `calc(100vh - ${top + 20}px)`,
-      }}
-    >
-      <div className="mb-4 text-sm leading-6 uppercase text-slate-900 dark:text-slate-100">
-        In this article
-      </div>
-      <Headings headings={headings} activeId={activeId} highlight={highlight} selector={selector} />
-      {children}
-    </nav>
+    <Collapsible.Root open={open} onOpenChange={setOpen}>
+      <nav
+        ref={outlineRef}
+        aria-label="Document Outline"
+        className={classNames(
+          'not-prose overflow-y-auto',
+          'transition-opacity duration-700', // Animation on load
+          className,
+        )}
+        style={{
+          top: top,
+          maxHeight: `calc(100vh - ${top + 20}px)`,
+        }}
+      >
+        <div className="flex flex-row gap-2 mb-4 text-sm leading-6 uppercase rounded-lg text-slate-900 dark:text-slate-100">
+          In this article
+          <Collapsible.Trigger asChild>
+            <button className="self-center flex-none rounded-md group hover:bg-slate-300/30 focus:outline outline-blue-200 outline-2">
+              <ChevronRightIcon
+                className="transition-transform duration-300 group-data-[state=open]:rotate-90 text-text-slate-700 dark:text-slate-100"
+                height="1.5rem"
+                width="1.5rem"
+              />
+            </button>
+          </Collapsible.Trigger>
+        </div>
+        <Collapsible.Content className="CollapsibleContent">
+          <Headings headings={headings} activeId={activeId} />
+          {children}
+        </Collapsible.Content>
+      </nav>
+    </Collapsible.Root>
   );
 };
 

package/src/components/Navigation/Search.tsx

@@ -0,0 +1,630 @@
+import { useEffect, useState, useMemo, useCallback, useRef, forwardRef } from 'react';
+import type { KeyboardEventHandler, Dispatch, SetStateAction, FormEvent, MouseEvent } from 'react';
+import { useNavigate, useFetcher } from '@remix-run/react';
+import {
+  ArrowTurnDownLeftIcon,
+  MagnifyingGlassIcon,
+  HashtagIcon,
+  Bars3BottomLeftIcon,
+  XCircleIcon,
+} from '@heroicons/react/24/solid';
+import { DocumentIcon } from '@heroicons/react/24/outline';
+import classNames from 'classnames';
+import * as Dialog from '@radix-ui/react-dialog';
+import * as VisuallyHidden from '@radix-ui/react-visually-hidden';
+import type { RankedSearchResult, HeadingLevel, MystSearchIndex } from '@myst-theme/search';
+import { SPACE_OR_PUNCTUATION, rankResults } from '@myst-theme/search';
+import {
+  useThemeTop,
+  useSearchFactory,
+  useLinkProvider,
+  withBaseurl,
+  useBaseurl,
+} from '@myst-theme/providers';
+
+/**
+ * Shim for string.matchAll
+ *
+ * @param text - text to repeatedly match with pattern
+ * @param pattern - global pattern
+ */
+function matchAll(text: string, pattern: RegExp) {
+  const matches = [];
+  let match;
+  while ((match = pattern.exec(text))) {
+    matches.push(match);
+  }
+  return matches;
+}
+
+/**
+ * Highlight a text string with an array of match words
+ *
+ * @param text - text to highlight
+ * @param result - search result to use for highlighting
+ * @param limit - limit to the number of tokens after first match
+ */
+function MarkedText({ text, matches, limit }: { text: string; matches: string[]; limit?: number }) {
+  // Split by delimeter, but _keep_ delimeter!
+  const splits = matchAll(text, SPACE_OR_PUNCTUATION);
+  const tokens: string[] = [];
+  let start = 0;
+  for (const splitMatch of splits) {
+    tokens.push(text.slice(start, splitMatch.index));
+    tokens.push(splitMatch[0]);
+    start = splitMatch.index + splitMatch[0].length;
+  }
+  tokens.push(text.slice(start));
+
+  // Build RegExp matching all highlight matches
+  const allTerms = matches.join('|');
+  const pattern = new RegExp(`^(${allTerms})`, 'i'); // Match prefix and total pattern, case-insensitively
+  const renderToken = (token: string) =>
+    pattern.test(token) ? (
+      <>
+        <mark className="text-blue-600 bg-inherit dark:text-blue-400 group-aria-selected:text-white group-aria-selected:underline">
+          {token}
+        </mark>
+      </>
+    ) : (
+      token
+    );
+  let firstIndex: number;
+  let lastIndex: number;
+  const hasLimit = limit !== undefined;
+
+  if (!hasLimit) {
+    firstIndex = 0;
+    lastIndex = tokens.length;
+  } else {
+    firstIndex = tokens.findIndex((token) => pattern.test(token));
+    lastIndex = firstIndex + limit;
+  }
+
+  if (tokens.length === 0) {
+    return <>{...tokens}</>;
+  } else {
+    const firstRenderer = renderToken(tokens[firstIndex]);
+    const remainingTokens = tokens.slice(firstIndex + 1, lastIndex);
+    const remainingRenderers = remainingTokens.map((token) => renderToken(token));
+
+    return (
+      <>
+        {hasLimit && '... '}
+        {firstRenderer}
+        {...remainingRenderers}
+        {hasLimit && ' ...'}
+      </>
+    );
+  }
+}
+
+/**
+ * Return true if the client is a Mac, false if not, or undefined if running on the server
+ */
+function isMac(): boolean | undefined {
+  if (typeof window === 'undefined') {
+    return undefined;
+  } else {
+    const hostIsMac = /mac/i.test(
+      (window.navigator as any).userAgentData?.platform ?? window.navigator.userAgent,
+    );
+    return hostIsMac;
+  }
+}
+
+// Blocking code to ensure that the pre-hydration state on the client matches the post-hydration state
+// The server with SSR cannot determine the client platform
+const clientThemeCode = `
+;(() => {
+const script = document.currentScript;
+const root = script.parentElement;
+
+const isMac = /mac/i.test(
+      window.navigator.userAgentData?.platform ?? window.navigator.userAgent,
+    );
+root.querySelectorAll(".hide-mac").forEach(node => {node.classList.add(isMac ? "hidden" : "block")});
+root.querySelectorAll(".show-mac").forEach(node => {node.classList.add(!isMac ? "hidden" : "block")});
+})()`;
+
+function BlockingPlatformLoader() {
+  return <script dangerouslySetInnerHTML={{ __html: clientThemeCode }} />;
+}
+
+/**
+ * Component that represents the keyboard shortcut for launching search
+ */
+function SearchShortcut() {
+  const hostIsMac = isMac();
+  return (
+    <div
+      aria-hidden
+      className="items-center hidden mx-1 font-mono text-sm text-gray-400 sm:flex gap-x-1"
+    >
+      <kbd
+        className={classNames(
+          'px-2 py-1 border border-gray-300 dark:border-gray-600 rounded-md',
+          'shadow-[0px_2px_0px_0px_rgba(0,0,0,0.08)] dark:shadow-none',
+          'hide-mac',
+          { hidden: hostIsMac === true },
+          { block: hostIsMac === false },
+        )}
+      >
+        CTRL
+      </kbd>
+      <kbd
+        className={classNames(
+          'px-2 py-1 border border-gray-300 dark:border-gray-600 rounded-md',
+          'shadow-[0px_2px_0px_0px_rgba(0,0,0,0.08)] dark:shadow-none',
+          'show-mac',
+          { hidden: hostIsMac === false },
+          { block: hostIsMac === true },
+        )}
+      >
+        ⌘
+      </kbd>
+      <kbd className="px-2 py-1 border border-gray-300 dark:border-gray-600 rounded-md shadow-[0px_2px_0px_0px_rgba(0,0,0,0.08)] dark:shadow-none ">
+        K
+      </kbd>
+      <BlockingPlatformLoader />
+    </div>
+  );
+}
+
+/**
+ * Renderer for a single search result
+ */
+function SearchResultItem({
+  result,
+  closeSearch,
+}: {
+  result: RankedSearchResult;
+  closeSearch?: () => void;
+}) {
+  const { hierarchy, type, url, queries } = result;
+  const Link = useLinkProvider();
+
+  // Render the icon
+  const iconRenderer =
+    type === 'lvl1' ? (
+      <DocumentIcon className="inline-block w-6 mx-2" />
+    ) : type === 'content' ? (
+      <Bars3BottomLeftIcon className="inline-block w-6 mx-2" />
+    ) : (
+      <HashtagIcon className="inline-block w-6 mx-2" />
+    );
+
+  // Generic "this document matched"
+  const title = result.type === 'content' ? result['content'] : hierarchy[type as HeadingLevel]!;
+  const matches = useMemo(() => queries.flatMap((query) => Object.keys(query.matches)), [queries]);
+
+  // Render the title, i.e. content or heading
+  const titleRenderer = (
+    <MarkedText text={title} matches={matches} limit={type === 'content' ? 16 : undefined} />
+  );
+
+  // Render the subtitle i.e. file name
+  let subtitleRenderer;
+  if (result.type === 'lvl1') {
+    subtitleRenderer = undefined;
+  } else {
+    const subtitle = result.hierarchy.lvl1!;
+    subtitleRenderer = <MarkedText text={subtitle} matches={matches} />;
+  }
+
+  const enterIconRenderer = (
+    <ArrowTurnDownLeftIcon className="invisible w-6 mx-2 group-aria-selected:visible" />
+  );
+
+  return (
+    <Link
+      className="block px-1 py-2 text-gray-700 rounded shadow-md dark:text-white group-aria-selected:bg-blue-600 group-aria-selected:text-white dark:shadow-none dark:bg-stone-800"
+      to={url}
+      // Close the main search on click
+      onClick={closeSearch}
+    >
+      <div className="flex flex-row h-11">
+        {iconRenderer}
+        <div className="flex flex-col justify-center grow">
+          <span className="text-sm">{titleRenderer}</span>
+          {subtitleRenderer && <span className="text-xs">{subtitleRenderer}</span>}
+        </div>
+        {enterIconRenderer}
+      </div>
+    </Link>
+  );
+}
+
+interface SearchResultsProps {
+  searchResults: RankedSearchResult[];
+  searchListID: string;
+  searchLabelID: string;
+  selectedIndex: number;
+  onHoverSelect: (index: number) => void;
+  className?: string;
+  closeSearch?: () => void;
+}
+
+function SearchResults({
+  searchResults,
+  searchListID,
+  searchLabelID,
+  className,
+  selectedIndex,
+  onHoverSelect,
+  closeSearch,
+}: SearchResultsProps) {
+  // Array of search item refs
+  const itemsRef = useRef<(HTMLLIElement | null)[]>([]);
+
+  // Ref to assign items
+  const setItemRef = useCallback(
+    (elem: HTMLLIElement) => {
+      if (!elem) {
+        return;
+      }
+      const index = parseInt(elem.dataset.index!);
+      itemsRef.current[index] = elem;
+    },
+    [itemsRef],
+  );
+
+  // Keep activeDescendent in sync wth selected index
+  const activeDescendent = useMemo(() => {
+    const item = itemsRef.current[selectedIndex];
+    if (!item) {
+      return '';
+    } else {
+      return item.id;
+    }
+  }, [selectedIndex, itemsRef]);
+
+  // If the select item changes, bring it into view
+  useEffect(() => {
+    const item = itemsRef.current[selectedIndex];
+    item?.scrollIntoView({ block: 'nearest' });
+  }, [selectedIndex]);
+
+  // Handle mouse movement events that set the current hovered element
+  const handleMouseMove = useCallback(
+    (event: MouseEvent<HTMLLIElement>) => {
+      const index = parseInt((event.currentTarget as HTMLLIElement).dataset.index!);
+      onHoverSelect(index);
+    },
+    [onHoverSelect],
+  );
+  return (
+    <div className="mt-4 overflow-y-scroll">
+      {searchResults.length ? (
+        <ul
+          // Accessiblity:
+          // indicate that this is a selectbox
+          role="listbox"
+          id={searchListID}
+          aria-label="Search results"
+          aria-labelledby={searchLabelID}
+          aria-orientation="vertical"
+          // Track focused item
+          aria-activedescendant={activeDescendent}
+          className={classNames('flex flex-col gap-y-2 px-1', className)}
+        >
+          {searchResults.map((result, index) => (
+            <li
+              key={result.id}
+              ref={setItemRef}
+              data-index={index}
+              // Accessiblity:
+              //   Indicate that this is an option
+              role="option"
+              //   Indicate whether this is selected
+              aria-selected={selectedIndex === index}
+              // Allow for nested-highlighting
+              className="group"
+              // Trigger selection on movement, so that scrolling doesn't trigger handler
+              onMouseMove={handleMouseMove}
+            >
+              <SearchResultItem result={result} closeSearch={closeSearch} />
+            </li>
+          ))}
+        </ul>
+      ) : (
+        <span>No results found.</span>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Build search implementation by requesting search index from server
+ */
+function useSearch() {
+  const baseURL = useBaseurl();
+  const fetcher = useFetcher();
+  const [enabled, setEnabled] = useState(true);
+  // Load index when this component is required
+  // TODO: this reloads every time the search box is opened.
+  //       we should lift the state up
+  useEffect(() => {
+    if (fetcher.state === 'idle' && fetcher.data == null) {
+      const searchURL = withBaseurl('/myst.search.json', baseURL);
+      fetcher.load(searchURL);
+    }
+  }, [fetcher, baseURL]);
+
+  const searchFactory = useSearchFactory();
+  const search = useMemo(() => {
+    if (!fetcher.data || !searchFactory) {
+      return undefined;
+    } else {
+      if (fetcher.data?.version && fetcher.data?.records) {
+        return searchFactory(fetcher.data as MystSearchIndex);
+      }
+      setEnabled(false);
+      return undefined;
+    }
+  }, [searchFactory, fetcher.data, setEnabled]);
+
+  // Implement pass-through
+  return { search, enabled };
+}
+
+interface SearchFormProps {
+  debounceTime: number;
+  searchResults: RankedSearchResult[] | undefined;
+  setSearchResults: Dispatch<SetStateAction<RankedSearchResult[] | undefined>>;
+  searchInputID: string;
+  searchListID: string;
+  searchLabelID: string;
+  selectedIndex: number;
+  setSelectedIndex: Dispatch<SetStateAction<number>>;
+  closeSearch?: () => void;
+}
+
+function SearchForm({
+  debounceTime,
+  searchResults,
+  setSearchResults,
+  searchInputID,
+  searchListID,
+  searchLabelID,
+  selectedIndex,
+  setSelectedIndex,
+  closeSearch,
+}: SearchFormProps) {
+  const [query, setQuery] = useState<string>('');
+  const { search: doSearch, enabled } = useSearch();
+
+  // Debounce user input
+  useEffect(() => {
+    const timeoutId = setTimeout(() => {
+      if (query != undefined && !!doSearch) {
+        doSearch(query).then((rawResults) => {
+          setSearchResults(
+            rawResults &&
+              rankResults(rawResults)
+                // Filter duplicates by URL
+                .filter((result, index, array) => result.url !== array[index - 1]?.url),
+          );
+        });
+      }
+    }, debounceTime);
+    return () => clearTimeout(timeoutId);
+  }, [doSearch, query, debounceTime]);
+  // Handle user input
+  const handleSearchChange = useCallback((event: React.ChangeEvent<HTMLInputElement>) => {
+    setQuery(event.target.value);
+  }, []);
+  // Handle item selection
+  const navigate = useNavigate();
+
+  // Handle item selection and navigation
+  const handleSearchKeyPress = useCallback<KeyboardEventHandler<HTMLInputElement>>(
+    (event) => {
+      // Ignore modifiers
+      if (event.ctrlKey || event.altKey || event.shiftKey) {
+        return;
+      }
+      if (!searchResults) {
+        return;
+      }
+
+      // Item selection
+      if (event.key === 'Enter') {
+        event.preventDefault();
+
+        const url = searchResults[selectedIndex]?.url;
+        if (url) {
+          navigate(url);
+          closeSearch?.();
+        }
+      }
+      // Item navigation
+      else if (event.key === 'ArrowUp' || event.key === 'ArrowDown') {
+        event.preventDefault();
+
+        if (event.key === 'ArrowUp') {
+          setSelectedIndex(selectedIndex > 0 ? selectedIndex - 1 : 0);
+        } else {
+          setSelectedIndex(
+            selectedIndex < searchResults.length - 1 ? selectedIndex + 1 : searchResults.length - 1,
+          );
+        }
+      }
+    },
+    [searchResults, selectedIndex],
+  ); // Our form doesn't use the submit function
+  const onSubmit = useCallback((event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+  }, []);
+
+  return (
+    <>
+      <form onSubmit={onSubmit}>
+        <div className="relative flex w-full h-10 flow-row gap-x-1 ">
+          <label id={searchListID} htmlFor={searchInputID}>
+            <MagnifyingGlassIcon className="absolute text-gray-400 inset-y-0 start-0 h-10 w-10 p-2.5 aspect-square flex items-center pointer-events-none" />
+          </label>
+          <input
+            autoComplete="off"
+            spellCheck="false"
+            disabled={!enabled}
+            autoCapitalize="false"
+            className={classNames(
+              'block flex-grow p-2 ps-10 placeholder-gray-400',
+              'border border-gray-300 dark:border-gray-600',
+              'rounded-lg bg-gray-50 dark:bg-gray-700',
+              'focus:ring-blue-500 dark:focus:ring-blue-500',
+              'focus:border-blue-500 dark:focus:border-blue-500',
+              'dark:placeholder-gray-400',
+              { 'border-red-500': !enabled },
+            )}
+            id={searchInputID}
+            aria-labelledby={searchLabelID}
+            aria-controls={searchListID}
+            placeholder="Search"
+            type="search"
+            required
+            onChange={handleSearchChange}
+            onKeyDown={handleSearchKeyPress}
+          />
+          <Dialog.Close asChild className="block grow-0 sm:hidden">
+            <button aria-label="Close">
+              <XCircleIcon className="flex items-center w-10 h-10 aspect-square" />
+            </button>
+          </Dialog.Close>
+        </div>
+      </form>
+      {!enabled && (
+        <div className="mx-2 mt-4 text-sm text-gray-500">
+          Search is not enabled for this site. :(
+        </div>
+      )}
+    </>
+  );
+}
+
+interface SearchPlaceholderButtonProps {
+  className?: string;
+  disabled?: boolean;
+}
+const SearchPlaceholderButton = forwardRef<
+  HTMLButtonElement,
+  SearchPlaceholderButtonProps & Dialog.DialogTriggerProps
+>(({ className, disabled, ...props }, ref) => {
+  return (
+    <button
+      {...props}
+      className={classNames(
+        className,
+        'flex items-center h-10 aspect-square sm:w-64 text-left text-gray-400',
+        'border border-gray-300 dark:border-gray-600',
+        'rounded-lg bg-gray-50 dark:bg-gray-700',
+        {
+          'hover:ring-blue-500': !disabled,
+          'dark:hover:ring-blue-500': !disabled,
+          'hover:border-blue-500': !disabled,
+          'dark:hover:border-blue-500': !disabled,
+        },
+      )}
+      disabled={!!disabled}
+      ref={ref}
+    >
+      <MagnifyingGlassIcon className="p-2.5 h-10 w-10 aspect-square" />
+      <span className="hidden sm:block grow">Search</span>
+      <SearchShortcut />
+    </button>
+  );
+});
+
+export interface SearchProps {
+  debounceTime?: number;
+}
+/**
+ * Component that implements a basic search interface
+ */
+export function Search({ debounceTime = 500 }: SearchProps) {
+  const [open, setOpen] = useState(false);
+  const [searchResults, setSearchResults] = useState<RankedSearchResult[] | undefined>();
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const top = useThemeTop();
+
+  // Clear search state on close
+  useEffect(() => {
+    if (!open) {
+      setSearchResults(undefined);
+      setSelectedIndex(0);
+    }
+  }, [open]);
+
+  // Trigger modal on keypress
+  const handleDocumentKeyPress = useCallback((event: KeyboardEvent) => {
+    if (event.key === 'k' && (isMac() ? event.metaKey : event.ctrlKey)) {
+      setOpen(true);
+      event.preventDefault();
+    }
+  }, []);
+
+  // Mount the document event handlers
+  useEffect(() => {
+    // attach the event listener
+    document.addEventListener('keydown', handleDocumentKeyPress);
+
+    // remove the event listener
+    return () => {
+      document.removeEventListener('keydown', handleDocumentKeyPress);
+    };
+  }, [handleDocumentKeyPress]);
+
+  const triggerClose = useCallback(() => setOpen(false), [setOpen]);
+  return (
+    <Dialog.Root open={open} onOpenChange={setOpen}>
+      <Dialog.Trigger asChild>
+        <SearchPlaceholderButton />
+      </Dialog.Trigger>
+      <Dialog.Portal>
+        <Dialog.Overlay className="fixed inset-0 bg-[#656c85cc] z-[1000]" />
+        <Dialog.Content
+          className="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"
+          // Store state as CSS variables so that we can set the style with tailwind variants
+          style={
+            {
+              '--content-top': `${top}px`,
+              '--content-max-height': `calc(90vh - var(--content-top))`,
+            } as React.CSSProperties
+          }
+        >
+          <VisuallyHidden.Root asChild>
+            <Dialog.Title>Search Website</Dialog.Title>
+          </VisuallyHidden.Root>
+          <VisuallyHidden.Root asChild>
+            <Dialog.Description>
+              Search articles and their contents using fuzzy-search and prefix-matching
+            </Dialog.Description>
+          </VisuallyHidden.Root>
+          <SearchForm
+            searchListID="search-list"
+            searchLabelID="search-label"
+            searchInputID="search-input"
+            debounceTime={debounceTime}
+            searchResults={searchResults}
+            setSearchResults={setSearchResults}
+            selectedIndex={selectedIndex}
+            setSelectedIndex={setSelectedIndex}
+            closeSearch={triggerClose}
+          />
+          {searchResults && (
+            <SearchResults
+              searchListID="search-list"
+              searchLabelID="search-label"
+              className="mt-4"
+              searchResults={searchResults}
+              selectedIndex={selectedIndex}
+              onHoverSelect={setSelectedIndex}
+              closeSearch={triggerClose}
+            />
+          )}
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}

package/src/components/Navigation/ThemeButton.tsx

@@ -8,7 +8,7 @@ export function ThemeButton({ className = 'w-8 h-8 mx-3' }: { className?: string
   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',
+        'theme rounded-full aspect-square 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={`Toggle theme between light and dark mode.`}

package/src/components/Navigation/TopNav.tsx

@@ -4,12 +4,8 @@ import { Menu, Transition } from '@headlessui/react';
 import { ChevronDownIcon, Bars3Icon as MenuIcon } from '@heroicons/react/24/solid';
 import type { SiteManifest, SiteNavItem } from 'myst-config';
 import { ThemeButton } from './ThemeButton.js';
-import {
-  useLinkProvider,
-  useNavLinkProvider,
-  useNavOpen,
-  useSiteManifest,
-} from '@myst-theme/providers';
+import { Search } from './Search.js';
+import { useNavLinkProvider, useNavOpen, useSiteManifest } from '@myst-theme/providers';
 import { LoadingBar } from './Loading.js';
 import { HomeLink } from './HomeLink.js';
 import { ActionMenu } from './ActionMenu.js';
@@ -107,7 +103,7 @@ export function NavItems({ nav }: { nav?: SiteManifest['nav'] }) {
   );
 }
 
-export function TopNav({ hideToc }: { hideToc?: boolean }) {
+export function TopNav({ hideToc, hideSearch }: { hideToc?: boolean; hideSearch?: boolean }) {
   const [open, setOpen] = useNavOpen();
   const config = useSiteManifest();
   const { title, nav, actions } = config ?? {};
@@ -134,6 +130,7 @@ export function TopNav({ hideToc }: { hideToc?: boolean }) {
         <div className="flex items-center flex-grow w-auto">
           <NavItems nav={nav} />
           <div className="flex-grow block"></div>
+          {!hideSearch && <Search />}
           <ThemeButton />
           <div className="block sm:hidden">
             <ActionMenu actions={actions} />