@vantagecompute/docusaurus-theme 0.4.8 → 0.5.0

package/src/index.cts

@@ -1,8 +1,38 @@
 import path from 'node:path';
-import { execSync } from 'node:child_process';
-import type { Plugin } from '@docusaurus/types';
+import {execSync} from 'node:child_process';
+import type {LoadContext, OptionValidationContext, Plugin} from '@docusaurus/types';
+import {
+  LOGO_HREF,
+  resolveNavbarVariant,
+  validateVantageThemeOptions,
+  type ResolvedVantageThemeOptions,
+  type VantageThemeOptions,
+} from './options.cjs';
+
+export type {NavbarLink, NavbarVariant, VantageThemeOptions} from './options.cjs';
+export {LOGO_HREF, MAX_NAVBAR_LINKS, resolveNavbarVariant} from './options.cjs';
+
+/**
+ * Shape of the global data the theme's client components read through
+ * `usePluginData('@vantagecompute/docusaurus-theme')`.
+ */
+export interface VantageThemeGlobalData {
+  variant: 'public' | 'developer';
+  logoHref: string;
+  navbarLinks: ResolvedVantageThemeOptions['navbarLinks'];
+}
+
+export default function themeVantage(
+  context: LoadContext,
+  options: ResolvedVantageThemeOptions,
+): Plugin {
+  const variant = resolveNavbarVariant(context.baseUrl);
+  const globalData: VantageThemeGlobalData = {
+    variant,
+    logoHref: LOGO_HREF[variant],
+    navbarLinks: options.navbarLinks,
+  };
 
-export default function themeVantage(): Plugin {
   return {
     name: '@vantagecompute/docusaurus-theme',
 
@@ -17,9 +47,26 @@ export default function themeVantage(): Plugin {
     getClientModules() {
       return [path.resolve(__dirname, '../src/css/custom.css')];
     },
+
+    // The navbar variant and the external buttons reach the client this way.
+    // Nothing in themeConfig.navbar is read by the theme's components.
+    contentLoaded({actions}) {
+      actions.setGlobalData(globalData);
+    },
   };
 }
 
+/**
+ * Docusaurus calls this before the plugin factory. Hand-rolled rather than Joi
+ * so the package carries no validation dependency; see src/options.cts.
+ */
+export function validateOptions({
+  options,
+}: OptionValidationContext<VantageThemeOptions | undefined, ResolvedVantageThemeOptions>):
+  ResolvedVantageThemeOptions {
+  return validateVantageThemeOptions(options);
+}
+
 /**
  * Returns the absolute path to this package's static directory.
  * Add this to your `staticDirectories` in docusaurus.config.js:
@@ -52,74 +99,3 @@ export function getProjectVersion(): string {
 
 // Re-export the rehype utility (plain JS, lives in src/utils/)
 export const rehypeTabsTransform = require(path.resolve(__dirname, '../src/utils/rehypeTabsTransform'));
-
-/**
- * Shape of a Docusaurus navbar or footer logo entry.
- */
-export interface ThemeLogo {
-  alt: string;
-  src: string;
-  srcDark?: string;
-  href: string;
-  target?: string;
-  width?: number;
-  height?: number;
-}
-
-/**
- * The Vantage colour brand mark, as a path relative to a served static
- * directory. It resolves once `staticDir` is in `staticDirectories`; no site
- * needs its own copy of the SVG.
- */
-const VANTAGE_LOGO_SRC = 'img/vantage-logo-color.svg';
-
-/**
- * Navbar logo for a Vantage documentation site.
- *
- * ```js
- * const { navbarLogo } = require('@vantagecompute/docusaurus-theme');
- * themeConfig: { navbar: { title: 'v8x', logo: navbarLogo, items: [...] } }
- * ```
- *
- * Deliberately has no `srcDark`. The single colour mark is drawn to read on
- * both colour modes, and a second asset would only be a second thing to keep
- * in sync.
- *
- * `href` points at the docs hub rather than the marketing site: from a spoke's
- * documentation the useful "home" is the rest of the documentation. `target`
- * is `_self` so that jump replaces the tab instead of opening a new one.
- *
- * Override by spreading, never by mutating -- the object is shared by every
- * site in the process:
- *
- * ```js
- * logo: { ...navbarLogo, href: 'https://docs.vantagecompute.ai/developer/' }
- * ```
- *
- * Omit `logo` entirely to render no navbar logo.
- */
-export const navbarLogo: ThemeLogo = {
-  alt: 'Vantage Compute Logo',
-  src: VANTAGE_LOGO_SRC,
-  href: 'https://docs.vantagecompute.ai',
-  target: '_self',
-};
-
-/**
- * Footer logo for a Vantage documentation site.
- *
- * ```js
- * const { footerLogo } = require('@vantagecompute/docusaurus-theme');
- * themeConfig: { footer: { style: 'dark', logo: footerLogo, links: [...] } }
- * ```
- *
- * Same mark as {@link navbarLogo}, but `href` points at the marketing site:
- * the footer is where a reader who has finished reading looks for the company.
- *
- * Override by spreading; omit `logo` to render no footer logo.
- */
-export const footerLogo: ThemeLogo = {
-  alt: 'Vantage Compute Logo',
-  src: VANTAGE_LOGO_SRC,
-  href: 'https://vantagecompute.ai',
-};

package/src/options.cts

@@ -0,0 +1,143 @@
+/**
+ * Theme options and the navbar variant rule. Pure functions with no Docusaurus
+ * imports, so they are tested directly against the compiled output.
+ */
+
+export type NavbarVariant = 'public' | 'developer';
+
+/** One external button in the developer navbar. Nothing else is configurable. */
+export interface NavbarLink {
+  label: string;
+  url: string;
+}
+
+/** What a site may pass in `themes: [['@vantagecompute/docusaurus-theme', {...}]]`. */
+export interface VantageThemeOptions {
+  /** External buttons, at most {@link MAX_NAVBAR_LINKS}. Rendered by the developer navbar only. */
+  navbarLinks?: NavbarLink[];
+}
+
+/**
+ * Options after validation. `id` is Docusaurus's plugin-instance id. When a
+ * plugin exports validateOptions, Docusaurus trusts the returned object to
+ * carry it (its own Joi path adds one), and names the plugin's generated data
+ * directory after it. Leaving it out crashes the build in path.join.
+ */
+export interface ResolvedVantageThemeOptions {
+  id: string;
+  navbarLinks: NavbarLink[];
+}
+
+const DEFAULT_PLUGIN_ID = 'default';
+
+/** Two is GitHub plus one registry (PyPI, npm, ...). More than that is a nav, and navs drift. */
+export const MAX_NAVBAR_LINKS = 2;
+
+/**
+ * Where the brand mark links, per variant. Baked in on purpose: a site cannot
+ * point its logo anywhere else, which is what keeps the hub consistent.
+ */
+export const LOGO_HREF: Record<NavbarVariant, string> = {
+  public: 'https://docs.vantagecompute.ai/',
+  developer: 'https://docs.vantagecompute.ai/developer/',
+};
+
+/**
+ * Every site published under /developer/ (the developer overview and every
+ * spoke) gets the developer navbar. Everything else gets the public one.
+ * Docusaurus normalises baseUrl to a leading and trailing slash before the
+ * plugin sees it.
+ */
+export function resolveNavbarVariant(baseUrl: string): NavbarVariant {
+  return baseUrl.startsWith('/developer/') ? 'developer' : 'public';
+}
+
+const PREFIX = '[@vantagecompute/docusaurus-theme]';
+
+function fail(message: string): never {
+  throw new Error(`${PREFIX} ${message}`);
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function validateLink(value: unknown, index: number): NavbarLink {
+  const where = `navbarLinks[${index}]`;
+  if (!isPlainObject(value)) {
+    fail(`${where} must be an object with "label" and "url".`);
+  }
+
+  const extra = Object.keys(value).filter((key) => key !== 'label' && key !== 'url');
+  if (extra.length > 0) {
+    fail(
+      `${where} has unsupported propert${extra.length === 1 ? 'y' : 'ies'} ` +
+        `${extra.map((k) => `"${k}"`).join(', ')}. Only "label" and "url" are ` +
+        `accepted; the icon, external-link marker and rel attributes come from the theme.`,
+    );
+  }
+
+  const {label, url} = value;
+  if (typeof label !== 'string' || label.trim() === '') {
+    fail(`${where}.label must be a non-empty string.`);
+  }
+  if (typeof url !== 'string' || url.trim() === '') {
+    fail(`${where}.url must be a non-empty string.`);
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return fail(`${where}.url must be an absolute http(s) URL, got "${url}".`);
+  }
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    fail(`${where}.url must be an absolute http(s) URL, got "${url}".`);
+  }
+
+  return {label: label.trim(), url};
+}
+
+/**
+ * Validate and normalise the theme options. Throws with a message that names
+ * the offending key, so a misconfigured spoke fails its build instead of
+ * quietly rendering something off-convention.
+ */
+export function validateVantageThemeOptions(options: unknown): ResolvedVantageThemeOptions {
+  if (options === undefined || options === null) {
+    return {id: DEFAULT_PLUGIN_ID, navbarLinks: []};
+  }
+  if (!isPlainObject(options)) {
+    fail('theme options must be an object.');
+  }
+
+  const {navbarLinks, id, ...unknown} = options;
+  const unknownKeys = Object.keys(unknown);
+  if (unknownKeys.length > 0) {
+    fail(
+      `unknown option${unknownKeys.length === 1 ? '' : 's'} ` +
+        `${unknownKeys.map((k) => `"${k}"`).join(', ')}. The only option is "navbarLinks".`,
+    );
+  }
+
+  const resolved: ResolvedVantageThemeOptions = {
+    id: typeof id === 'string' ? id : DEFAULT_PLUGIN_ID,
+    navbarLinks: [],
+  };
+
+  if (navbarLinks === undefined) {
+    return resolved;
+  }
+  if (!Array.isArray(navbarLinks)) {
+    fail('"navbarLinks" must be an array of {label, url} objects.');
+  }
+  if (navbarLinks.length > MAX_NAVBAR_LINKS) {
+    fail(
+      `"navbarLinks" allows at most ${MAX_NAVBAR_LINKS} entries, got ${navbarLinks.length}. ` +
+        `GitHub plus one package registry is the intended use.`,
+    );
+  }
+
+  resolved.navbarLinks = navbarLinks.map(validateLink);
+  return resolved;
+}

package/src/theme/Footer/index.js

@@ -0,0 +1,9 @@
+/**
+ * No Vantage documentation site renders a footer. The collapse-sidebar control
+ * already frames the bottom of the screen, and the links a footer would carry
+ * are the navbar's external buttons. A site that still declares
+ * themeConfig.footer builds fine and renders nothing.
+ */
+export default function Footer() {
+  return null;
+}

package/src/theme/MDXComponents/TableScroll.jsx

@@ -0,0 +1,19 @@
+/**
+ * A markdown table inside a horizontal scroll region.
+ *
+ * The theme frames tables with a border and a radius. Doing that on the table
+ * itself needed `overflow: hidden`, which removed the `display: block;
+ * overflow-x: auto` Docusaurus ships for wide tables, and on a 345px phone
+ * column a four-column reference table squeezed to 61px columns and 171px
+ * rows. The wrapper carries the frame now (see `.table-scroll` in
+ * src/css/custom.css); the table keeps its natural width and scrolls.
+ *
+ * `role="region"` plus `tabIndex` so a keyboard user can reach and scroll it.
+ */
+export default function TableScroll(props) {
+  return (
+    <div className="table-scroll" role="region" aria-label="Table, scrolls horizontally" tabIndex={0}>
+      <table {...props} />
+    </div>
+  );
+}

package/src/theme/MDXComponents/index.js

@@ -0,0 +1,17 @@
+// Routes every markdown `table` through TableScroll. Docusaurus's own map has
+// no `table` entry, so this adds one rather than replacing anything.
+//
+// @theme-init, not @theme-original: this file ships inside a theme package that
+// sits in the theme stack, so @theme-original/MDXComponents would resolve back
+// to this same module and recurse. See src/theme/Navbar/Logo for the same note.
+//
+// A site that already wraps `table` itself (vantage-docs did, before this
+// shipped) must drop its own wrapper, or every table renders in two scroll
+// regions. MIGRATION.md, Part 3.
+import MDXComponents from '@theme-init/MDXComponents';
+import TableScroll from './TableScroll';
+
+export default {
+  ...MDXComponents,
+  table: TableScroll,
+};

package/src/theme/Navbar/Content/index.jsx

@@ -0,0 +1,91 @@
+import React from 'react';
+import clsx from 'clsx';
+import {ErrorCauseBoundary, ThemeClassNames} from '@docusaurus/theme-common';
+import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
+import NavbarItem from '@theme/NavbarItem';
+import NavbarColorModeToggle from '@theme/Navbar/ColorModeToggle';
+import SearchBar from '@theme/SearchBar';
+import NavbarMobileSidebarToggle from '@theme/Navbar/MobileSidebar/Toggle';
+import NavbarLogo from '@theme/Navbar/Logo';
+import NavbarSearch from '@theme/Navbar/Search';
+import NavbarSiteActions from '@theme/Navbar/SiteActions';
+import {toNavbarItems, useVantageNavbar} from '../useVantageNavbar';
+
+import styles from './styles.module.css';
+
+/**
+ * The navbar, replacing theme-classic's Navbar/Content.
+ *
+ * Two fixed variants, chosen by the theme from the site's baseUrl:
+ *
+ *   public     logo | search, SiteActions slot, colour-mode toggle
+ *   developer  logo + centred title and version | external buttons, toggle
+ *
+ * themeConfig.navbar.items is never read. A site that still declares items
+ * gets no error and no rendering; the convention is the theme's to hold.
+ */
+function ExternalLinks({items}) {
+  return (
+    <>
+      {items.map((item, i) => (
+        <ErrorCauseBoundary
+          key={i}
+          onError={(error) =>
+            new Error(
+              `A theme navbar link failed to render: ${JSON.stringify(item)}`,
+              {cause: error},
+            )
+          }>
+          <NavbarItem {...item} />
+        </ErrorCauseBoundary>
+      ))}
+    </>
+  );
+}
+
+function NavbarContentLayout({left, right}) {
+  return (
+    <div className="navbar__inner">
+      <div className={clsx(ThemeClassNames.layout.navbar.containerLeft, 'navbar__items')}>
+        {left}
+      </div>
+      <div
+        className={clsx(
+          ThemeClassNames.layout.navbar.containerRight,
+          'navbar__items navbar__items--right',
+        )}>
+        {right}
+      </div>
+    </div>
+  );
+}
+
+export default function NavbarContent() {
+  const mobileSidebar = useNavbarMobileSidebar();
+  const {variant, links} = useVantageNavbar();
+
+  const left = (
+    <>
+      {!mobileSidebar.disabled && <NavbarMobileSidebarToggle />}
+      <NavbarLogo />
+    </>
+  );
+
+  const right =
+    variant === 'developer' ? (
+      <>
+        <ExternalLinks items={toNavbarItems(links)} />
+        <NavbarColorModeToggle className={styles.colorModeToggle} />
+      </>
+    ) : (
+      <>
+        <NavbarSearch>
+          <SearchBar />
+        </NavbarSearch>
+        <NavbarSiteActions />
+        <NavbarColorModeToggle className={styles.colorModeToggle} />
+      </>
+    );
+
+  return <NavbarContentLayout left={left} right={right} />;
+}

package/src/theme/Navbar/Content/styles.module.css

@@ -0,0 +1,6 @@
+/* The mobile drawer header has its own toggle. */
+@media (max-width: 996px) {
+  .colorModeToggle {
+    display: none;
+  }
+}

package/src/theme/Navbar/Logo/index.jsx

@@ -1,36 +1,39 @@
 import React from 'react';
-// Must be @theme-init, NOT @theme-original. This component ships inside a
-// theme package that sits in the theme stack, so @theme-original/Navbar/Logo
-// resolves back to this same component -- React SSR then recurses without
-// bound and exhausts the heap during static site generation. @theme-init is
-// the alias for a theme wrapping the implementation below it in the stack.
-import Logo from '@theme-init/Navbar/Logo';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import {useVantageNavbar} from '../useVantageNavbar';
+
+// The one colour mark reads on both colour modes, so there is no srcDark and
+// no second asset to keep in sync. Resolves through staticDir, which every
+// Vantage site lists in staticDirectories.
+const LOGO_SRC = 'img/vantage-logo-color.svg';
 
 /**
- * Brand logo on the left, plus a centered title with the project version
- * immediately to its right.
+ * The brand link, the centred title and the version badge.
+ *
+ * Replaces theme-classic's Logo outright instead of wrapping it, because the
+ * href is not the site's to choose: the theme bakes it per variant (the docs
+ * root for the public navbar, the developer overview for the developer one).
+ * A plain anchor rather than @docusaurus/Link because the jump crosses SPA
+ * boundaries and should be a full navigation. Same tab: command-click covers
+ * "open in a new tab".
  *
- * The title cannot just be centered in place: theme-classic renders it inside
- * the brand <a>, beside the logo, so centering it would drag the logo along.
- * Instead the in-brand title is hidden by CSS and re-rendered here as its own
- * absolutely-centered element, which lets the version badge sit next to it.
+ * The markup mirrors theme-classic's (navbar__brand > navbar__logo > img,
+ * plus b.navbar__title) so Infima's and this theme's CSS keep applying. On
+ * desktop the in-brand title is hidden by CSS and re-rendered centred below,
+ * which is what lets the version badge sit beside it.
  */
-export default function LogoWrapper(props) {
-  const {siteConfig} = useDocusaurusContext();
-
-  const raw = siteConfig.customFields?.projectVersion;
-  const version = raw
-    ? String(raw).startsWith('v')
-      ? String(raw)
-      : `v${raw}`
-    : null;
-
-  const title = siteConfig.themeConfig?.navbar?.title;
+export default function NavbarLogo() {
+  const {logoHref, title, version} = useVantageNavbar();
+  const src = useBaseUrl(LOGO_SRC);
 
   return (
     <>
-      <Logo {...props} />
+      <a className="navbar__brand" href={logoHref}>
+        <div className="navbar__logo">
+          <img src={src} alt="Vantage Compute Logo" />
+        </div>
+        {title && <b className="navbar__title text--truncate">{title}</b>}
+      </a>
       {(title || version) && (
         <div className="navbar__center-title">
           {title && <span className="navbar__center-title-text">{title}</span>}

package/src/theme/Navbar/MobileSidebar/PrimaryMenu/index.jsx

@@ -0,0 +1,28 @@
+import React from 'react';
+import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
+import NavbarItem from '@theme/NavbarItem';
+import {toNavbarItems, useVantageNavbar} from '../../useVantageNavbar';
+
+/**
+ * The primary panel of the mobile drawer. theme-classic fills it from
+ * themeConfig.navbar.items; this theme fills it from the same external
+ * buttons the developer navbar shows. The public navbar has nothing to put
+ * here (search and the site's actions stay in the bar), so the panel is empty
+ * and the drawer opens straight onto the docs sidebar.
+ */
+export default function NavbarMobilePrimaryMenu() {
+  const mobileSidebar = useNavbarMobileSidebar();
+  const {variant, links} = useVantageNavbar();
+
+  if (variant !== 'developer' || links.length === 0) {
+    return null;
+  }
+
+  return (
+    <ul className="menu__list">
+      {toNavbarItems(links).map((item, i) => (
+        <NavbarItem mobile {...item} onClick={() => mobileSidebar.toggle()} key={i} />
+      ))}
+    </ul>
+  );
+}

package/src/theme/Navbar/SiteActions/index.jsx

@@ -0,0 +1,11 @@
+/**
+ * A slot in the public navbar, between search and the colour-mode toggle.
+ * Empty here. The main docs site overrides it in its own src/theme/ to render
+ * its Ask AI button; that component talks to the Vantage AI backend and does
+ * not belong in a theme package.
+ *
+ * The developer navbar does not render this slot.
+ */
+export default function NavbarSiteActions() {
+  return null;
+}

package/src/theme/Navbar/useVantageNavbar.js

@@ -0,0 +1,48 @@
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {usePluginData} from '@docusaurus/useGlobalData';
+
+/**
+ * Everything the theme's navbar components need, in one place. The variant,
+ * the brand-link href and the external buttons come from the theme's Node
+ * side (setGlobalData in lib/index.cjs). The title and version come from the
+ * site config. themeConfig.navbar is deliberately never read.
+ */
+export function useVantageNavbar() {
+  const {siteConfig} = useDocusaurusContext();
+  const {variant, logoHref, navbarLinks} = usePluginData('@vantagecompute/docusaurus-theme');
+
+  const raw = siteConfig.customFields?.projectVersion;
+  const version = raw
+    ? String(raw).startsWith('v')
+      ? String(raw)
+      : `v${raw}`
+    : null;
+
+  return {
+    variant,
+    logoHref,
+    links: navbarLinks,
+    // The developer navbar names the project beside its version, which is
+    // how a reader confirms they are on the version they think they are.
+    // The public navbar is logo-only.
+    title: variant === 'developer' ? siteConfig.title : null,
+    version,
+  };
+}
+
+/**
+ * Map the validated {label, url} links onto theme-classic NavbarItem props.
+ * External destinations open in a new tab, the accepted convention for
+ * leaving a site. NavbarNavLink appends the external-link icon on its own
+ * because href is external and label is set.
+ */
+export function toNavbarItems(links) {
+  return links.map((link) => ({
+    label: link.label,
+    href: link.url,
+    position: 'right',
+    target: '_blank',
+    rel: 'noopener noreferrer',
+    className: 'navbar__external-link',
+  }));
+}