🧭 Move collapsed top-bar to primary sidebar on small screens (#444)

.changeset/forty-carrots-cry.md

@@ -0,0 +1,7 @@
+---
+'@myst-theme/frontmatter': patch
+'@myst-theme/site': patch
+'@myst-theme/book': patch
+---
+
+Some alignment fixes, leaving more control over content top alignment to the theme

.changeset/mighty-ears-breathe.md

@@ -0,0 +1,6 @@
+---
+'@myst-theme/site': patch
+'@myst-theme/book': patch
+---
+
+Renamed `Navigation` component and split for re-use in different (composed/multi-site) themes

.changeset/olive-baboons-accept.md

@@ -0,0 +1,6 @@
+---
+'@myst-theme/site': minor
+'@myst-theme/book': patch
+---
+
+Rework TOC to PrimarySidebar

.changeset/strong-cars-beam.md

@@ -0,0 +1,5 @@
+---
+'@myst-theme/common': patch
+---
+
+Modified `getProjectHeadings` to work with plain `projectSlugs` to support custom theme routes that use `baseurl` but have no separate project.

packages/common/src/utils.ts

@@ -40,7 +40,10 @@ export function getProjectHeadings(
     },
     ...project.pages.map((p) => {
       if (!('slug' in p)) return p;
-      return { ...p, path: projectSlug ? `/${project.slug}/${p.slug}` : `/${p.slug}` };
+      return {
+        ...p,
+        path: projectSlug && project.slug ? `/${project.slug}/${p.slug}` : `/${p.slug}`,
+      };
     }),
   ];
   if (opts.addGroups) {

packages/frontmatter/src/FrontmatterBlock.tsx

@@ -235,7 +235,7 @@ export function FrontmatterBlock({
       className={classNames(className)}
     >
       {showHeaderBlock && (
-        <div className="flex items-center h-6 mt-3 mb-5 text-sm font-light">
+        <div className="flex items-center h-6 mb-5 text-sm font-light">
           {subject && (
             <div
               className={classNames('flex-none pr-2 smallcaps', {

packages/site/CHANGELOG.md

@@ -1077,10 +1077,10 @@
 - 8af808bf: Remove css updates for document nav and outline from React state
 
   ```tsx
-  const { container, toc } = useTocHeight(top);
+  const { container, toc } = useSidebarHeight(top);
 
   // Update the nav and article, removing the height
-  <Navigation tocRef={toc} ... />
+  <Navigation sidebarRef={toc} ... />
   <article ref={container} ... />
   ```
 

packages/site/package.json

@@ -10,9 +10,13 @@
   "license": "MIT",
   "sideEffects": false,
   "scripts": {
+    "clean": "rimraf dist",
     "compile": "tsc --noEmit",
     "lint": "eslint src/**/*.ts*",
-    "lint:format": "prettier --check \"src/**/*.{ts,tsx,md}\""
+    "lint:format": "prettier --check \"src/**/*.{ts,tsx,md}\"",
+    "dev": "npm-run-all --parallel \"build:* -- --watch\"",
+    "build:esm": "tsc",
+    "build": "npm-run-all -l clean -p build:esm"
   },
   "dependencies": {
     "@headlessui/react": "^1.7.15",

packages/site/src/components/Headers.tsx

@@ -85,7 +85,7 @@ export function ArticleHeader({
               frontmatter={rest}
               authorStyle="list"
               className={classNames('flex-grow', {
-                'pt-4 px-6': frontmatter?.banner,
+                'pt-6 px-6': frontmatter?.banner,
                 ...positionFrontmatter,
               })}
               hideBadges

packages/site/src/components/Navigation/InlineTableOfContents.tsx

@@ -0,0 +1,25 @@
+import { useSiteManifest } from '@myst-theme/providers';
+import { getProjectHeadings } from '@myst-theme/common';
+import { Toc } from './TableOfContentsItems.js';
+
+export const InlineTableOfContents = ({
+  projectSlug,
+  sidebarRef,
+  className = 'flex-grow overflow-y-auto max-w-[350px]',
+}: {
+  projectSlug?: string;
+  className?: string;
+  sidebarRef?: React.RefObject<HTMLElement>;
+}) => {
+  const config = useSiteManifest();
+  if (!config) return null;
+  const headings = getProjectHeadings(config, projectSlug, {
+    addGroups: false,
+  });
+  if (!headings) return null;
+  return (
+    <nav aria-label="Table of Contents" className={className} ref={sidebarRef}>
+      <Toc headings={headings} />
+    </nav>
+  );
+};

packages/site/src/components/Navigation/Link.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import { useLinkProvider, useNavLinkProvider } from '@myst-theme/providers';
+
+export function ExternalOrInternalLink({
+  to,
+  className,
+  children,
+  nav,
+  onClick,
+  prefetch = 'intent',
+}: {
+  to: string;
+  className?: string | ((props: { isActive: boolean }) => string);
+  children: React.ReactNode;
+  nav?: boolean;
+  onClick?: () => void;
+  prefetch?: 'intent' | 'render' | 'none';
+}) {
+  const Link = useLinkProvider();
+  const NavLink = useNavLinkProvider();
+  const staticClass = typeof className === 'function' ? className({ isActive: false }) : className;
+  if (to.startsWith('http') || to.startsWith('mailto:')) {
+    return (
+      <a
+        href={to}
+        target="_blank"
+        rel="noopener noreferrer"
+        className={staticClass}
+        onClick={onClick}
+      >
+        {children}
+      </a>
+    );
+  }
+  if (nav) {
+    return (
+      <NavLink prefetch={prefetch} to={to} className={className} onClick={onClick}>
+        {children}
+      </NavLink>
+    );
+  }
+  return (
+    <Link prefetch={prefetch} to={to} className={staticClass} onClick={onClick}>
+      {children}
+    </Link>
+  );
+}

packages/site/src/components/Navigation/Navigation.tsx

@@ -1,37 +1,106 @@
-import { useNavOpen, useThemeTop } from '@myst-theme/providers';
-import { TableOfContents } from './TableOfContents.js';
+import { useNavOpen, useSiteManifest, useThemeTop } from '@myst-theme/providers';
+import { PrimarySidebar } from './PrimarySidebar.js';
+import type { Heading } from '@myst-theme/common';
+import { getProjectHeadings } from '@myst-theme/common';
+import type { SiteManifest } from 'myst-config';
 
-export function Navigation({
+/**
+ * PrimaryNavigation will load nav links and headers from the site manifest and display
+ * them in a mobile-friendly format.
+ */
+export const PrimaryNavigation = ({
   children,
   projectSlug,
-  tocRef,
+  sidebarRef,
   hide_toc,
+  mobileOnly,
   footer,
 }: {
   children?: React.ReactNode;
   projectSlug?: string;
-  tocRef?: React.RefObject<HTMLDivElement>;
+  sidebarRef?: React.RefObject<HTMLDivElement>;
   hide_toc?: boolean;
+  mobileOnly?: boolean;
   footer?: React.ReactNode;
-}) {
+}) => {
+  const config = useSiteManifest();
+  if (!config) return null;
+
+  const headings = getProjectHeadings(config, projectSlug, {
+    addGroups: false,
+  });
+
+  const { nav } = config;
+
+  return (
+    <ConfigurablePrimaryNavigation
+      children={children}
+      sidebarRef={sidebarRef}
+      hide_toc={hide_toc}
+      mobileOnly={mobileOnly}
+      nav={nav}
+      headings={headings}
+      footer={footer}
+    />
+  );
+};
+
+/**
+@deprecated use PrimaryNavigation instead
+ */
+export const Navigation = PrimaryNavigation;
+
+/**
+ * ConfigurablePrimaryNavigation will display a mobile-friendly navigation sidebar based on the
+ * nav, headings, and footer provided by the caller. Use this in situations where the PrimaryNavigation
+ * component may pick up the wrong SiteManifest.
+ */
+export const ConfigurablePrimaryNavigation = ({
+  children,
+  sidebarRef,
+  hide_toc,
+  mobileOnly,
+  nav,
+  headings,
+  footer,
+}: {
+  children?: React.ReactNode;
+  sidebarRef?: React.RefObject<HTMLDivElement>;
+  hide_toc?: boolean;
+  mobileOnly?: boolean;
+  nav?: SiteManifest['nav'];
+  headings?: Heading[];
+  footer?: React.ReactNode;
+}) => {
   const [open, setOpen] = useNavOpen();
   const top = useThemeTop();
+
   if (children)
     console.warn(
       `Including children in Navigation can break keyboard accessbility and is deprecated. Please move children to the page component.`,
     );
+
+  // the logic on the following line looks wrong, this will return `null` or `<></>`
+  // we should just return `null` if `hide_toc` is true?
   if (hide_toc) return children ? null : <>{children}</>;
+
   return (
     <>
-      {open && (
+      {open && !mobileOnly && headings && (
         <div
           className="fixed inset-0 z-30 bg-black opacity-50"
           style={{ marginTop: top }}
           onClick={() => setOpen(false)}
         ></div>
       )}
-      <TableOfContents tocRef={tocRef} projectSlug={projectSlug} footer={footer} />
+      <PrimarySidebar
+        sidebarRef={sidebarRef}
+        nav={nav}
+        headings={headings}
+        footer={footer}
+        mobileOnly={mobileOnly}
+      />
       {children}
     </>
   );
-}
+};