@docusaurus/theme-common 2.0.0-beta.ff31de0ff → 2.0.1

package/src/utils/docsUtils.tsx

@@ -0,0 +1,334 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {useMemo} from 'react';
+import {matchPath, useLocation} from '@docusaurus/router';
+import renderRoutes from '@docusaurus/renderRoutes';
+import {
+  useAllDocsData,
+  useActivePlugin,
+  useActiveDocContext,
+  useLatestVersion,
+  type GlobalVersion,
+  type GlobalSidebar,
+  type GlobalDoc,
+} from '@docusaurus/plugin-content-docs/client';
+import type {Props as DocPageProps} from '@theme/DocPage';
+import {useDocsPreferredVersion} from '../contexts/docsPreferredVersion';
+import {useDocsVersion} from '../contexts/docsVersion';
+import {useDocsSidebar} from '../contexts/docsSidebar';
+import {uniq} from './jsUtils';
+import {isSamePath} from './routesUtils';
+import type {
+  PropSidebar,
+  PropSidebarItem,
+  PropSidebarItemCategory,
+  PropVersionDoc,
+  PropSidebarBreadcrumbsItem,
+} from '@docusaurus/plugin-content-docs';
+
+// TODO not ideal, see also "useDocs"
+export const isDocsPluginEnabled: boolean = !!useAllDocsData;
+
+/**
+ * A null-safe way to access a doc's data by ID in the active version.
+ */
+export function useDocById(id: string): PropVersionDoc;
+/**
+ * A null-safe way to access a doc's data by ID in the active version.
+ */
+export function useDocById(id: string | undefined): PropVersionDoc | undefined;
+export function useDocById(id: string | undefined): PropVersionDoc | undefined {
+  const version = useDocsVersion();
+  if (!id) {
+    return undefined;
+  }
+  const doc = version.docs[id];
+  if (!doc) {
+    throw new Error(`no version doc found by id=${id}`);
+  }
+  return doc;
+}
+
+/**
+ * Pure function, similar to `Array#find`, but works on the sidebar tree.
+ */
+export function findSidebarCategory(
+  sidebar: PropSidebar,
+  predicate: (category: PropSidebarItemCategory) => boolean,
+): PropSidebarItemCategory | undefined {
+  for (const item of sidebar) {
+    if (item.type === 'category') {
+      if (predicate(item)) {
+        return item;
+      }
+      const subItem = findSidebarCategory(item.items, predicate);
+      if (subItem) {
+        return subItem;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Best effort to assign a link to a sidebar category. If the category doesn't
+ * have a link itself, we link to the first sub item with a link.
+ */
+export function findFirstCategoryLink(
+  item: PropSidebarItemCategory,
+): string | undefined {
+  if (item.href) {
+    return item.href;
+  }
+
+  for (const subItem of item.items) {
+    if (subItem.type === 'link') {
+      return subItem.href;
+    } else if (subItem.type === 'category') {
+      const categoryLink = findFirstCategoryLink(subItem);
+      if (categoryLink) {
+        return categoryLink;
+      }
+    }
+    // Could be "html" items
+  }
+  return undefined;
+}
+
+/**
+ * Gets the category associated with the current location. Should only be used
+ * on category index pages.
+ */
+export function useCurrentSidebarCategory(): PropSidebarItemCategory {
+  const {pathname} = useLocation();
+  const sidebar = useDocsSidebar();
+  if (!sidebar) {
+    throw new Error('Unexpected: cant find current sidebar in context');
+  }
+  const category = findSidebarCategory(sidebar.items, (item) =>
+    isSamePath(item.href, pathname),
+  );
+  if (!category) {
+    throw new Error(
+      `${pathname} is not associated with a category. useCurrentSidebarCategory() should only be used on category index pages.`,
+    );
+  }
+  return category;
+}
+
+const isActive = (testedPath: string | undefined, activePath: string) =>
+  typeof testedPath !== 'undefined' && isSamePath(testedPath, activePath);
+const containsActiveSidebarItem = (
+  items: PropSidebarItem[],
+  activePath: string,
+) => items.some((subItem) => isActiveSidebarItem(subItem, activePath));
+
+/**
+ * Checks if a sidebar item should be active, based on the active path.
+ */
+export function isActiveSidebarItem(
+  item: PropSidebarItem,
+  activePath: string,
+): boolean {
+  if (item.type === 'link') {
+    return isActive(item.href, activePath);
+  }
+
+  if (item.type === 'category') {
+    return (
+      isActive(item.href, activePath) ||
+      containsActiveSidebarItem(item.items, activePath)
+    );
+  }
+
+  return false;
+}
+
+/**
+ * Gets the breadcrumbs of the current doc page, based on its sidebar location.
+ * Returns `null` if there's no sidebar or breadcrumbs are disabled.
+ */
+export function useSidebarBreadcrumbs(): PropSidebarBreadcrumbsItem[] | null {
+  const sidebar = useDocsSidebar();
+  const {pathname} = useLocation();
+  const breadcrumbsOption = useActivePlugin()?.pluginData.breadcrumbs;
+
+  if (breadcrumbsOption === false || !sidebar) {
+    return null;
+  }
+
+  const breadcrumbs: PropSidebarBreadcrumbsItem[] = [];
+
+  function extract(items: PropSidebar) {
+    for (const item of items) {
+      if (
+        (item.type === 'category' &&
+          (isSamePath(item.href, pathname) || extract(item.items))) ||
+        (item.type === 'link' && isSamePath(item.href, pathname))
+      ) {
+        breadcrumbs.push(item);
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  extract(sidebar.items);
+
+  return breadcrumbs.reverse();
+}
+
+/**
+ * "Version candidates" are mostly useful for the layout components, which must
+ * be able to work on all pages. For example, if a user has `{ type: "doc",
+ * docId: "intro" }` as a navbar item, which version does that refer to? We
+ * believe that it could refer to at most three version candidates:
+ *
+ * 1. The **active version**, the one that the user is currently browsing. See
+ * {@link useActiveDocContext}.
+ * 2. The **preferred version**, the one that the user last visited. See
+ * {@link useDocsPreferredVersion}.
+ * 3. The **latest version**, the "default". See {@link useLatestVersion}.
+ *
+ * @param docsPluginId The plugin ID to get versions from.
+ * @returns An array of 1~3 versions with priorities defined above, guaranteed
+ * to be unique and non-sparse. Will be memoized, hence stable for deps array.
+ */
+export function useDocsVersionCandidates(
+  docsPluginId?: string,
+): [GlobalVersion, ...GlobalVersion[]] {
+  const {activeVersion} = useActiveDocContext(docsPluginId);
+  const {preferredVersion} = useDocsPreferredVersion(docsPluginId);
+  const latestVersion = useLatestVersion(docsPluginId);
+  return useMemo(
+    () =>
+      uniq(
+        [activeVersion, preferredVersion, latestVersion].filter(Boolean),
+      ) as [GlobalVersion, ...GlobalVersion[]],
+    [activeVersion, preferredVersion, latestVersion],
+  );
+}
+
+/**
+ * The layout components, like navbar items, must be able to work on all pages,
+ * even on non-doc ones where there's no version context, so a sidebar ID could
+ * be ambiguous. This hook would always return a sidebar to be linked to. See
+ * also {@link useDocsVersionCandidates} for how this selection is done.
+ *
+ * @throws This hook throws if a sidebar with said ID is not found.
+ */
+export function useLayoutDocsSidebar(
+  sidebarId: string,
+  docsPluginId?: string,
+): GlobalSidebar {
+  const versions = useDocsVersionCandidates(docsPluginId);
+  return useMemo(() => {
+    const allSidebars = versions.flatMap((version) =>
+      version.sidebars ? Object.entries(version.sidebars) : [],
+    );
+    const sidebarEntry = allSidebars.find(
+      (sidebar) => sidebar[0] === sidebarId,
+    );
+    if (!sidebarEntry) {
+      throw new Error(
+        `Can't find any sidebar with id "${sidebarId}" in version${
+          versions.length > 1 ? 's' : ''
+        } ${versions.map((version) => version.name).join(', ')}".
+  Available sidebar ids are:
+  - ${Object.keys(allSidebars).join('\n- ')}`,
+      );
+    }
+    return sidebarEntry[1];
+  }, [sidebarId, versions]);
+}
+
+/**
+ * The layout components, like navbar items, must be able to work on all pages,
+ * even on non-doc ones where there's no version context, so a doc ID could be
+ * ambiguous. This hook would always return a doc to be linked to. See also
+ * {@link useDocsVersionCandidates} for how this selection is done.
+ *
+ * @throws This hook throws if a doc with said ID is not found.
+ */
+export function useLayoutDoc(
+  docId: string,
+  docsPluginId?: string,
+): GlobalDoc | null {
+  const versions = useDocsVersionCandidates(docsPluginId);
+  return useMemo(() => {
+    const allDocs = versions.flatMap((version) => version.docs);
+    const doc = allDocs.find((versionDoc) => versionDoc.id === docId);
+    if (!doc) {
+      const isDraft = versions
+        .flatMap((version) => version.draftIds)
+        .includes(docId);
+      // Drafts should be silently filtered instead of throwing
+      if (isDraft) {
+        return null;
+      }
+      throw new Error(
+        `DocNavbarItem: couldn't find any doc with id "${docId}" in version${
+          versions.length > 1 ? 's' : ''
+        } ${versions.map((version) => version.name).join(', ')}".
+Available doc ids are:
+- ${uniq(allDocs.map((versionDoc) => versionDoc.id)).join('\n- ')}`,
+      );
+    }
+    return doc;
+  }, [docId, versions]);
+}
+
+// TODO later read version/route directly from context
+/**
+ * The docs plugin creates nested routes, with the top-level route providing the
+ * version metadata, and the subroutes creating individual doc pages. This hook
+ * will match the current location against all known sub-routes.
+ *
+ * @param props The props received by `@theme/DocPage`
+ * @returns The data of the relevant document at the current location, or `null`
+ * if no document associated with the current location can be found.
+ */
+export function useDocRouteMetadata({
+  route,
+  versionMetadata,
+}: DocPageProps): null | {
+  /** The element that should be rendered at the current location. */
+  docElement: JSX.Element;
+  /**
+   * The name of the sidebar associated with the current doc. `sidebarName` and
+   * `sidebarItems` correspond to the value of {@link useDocsSidebar}.
+   */
+  sidebarName: string | undefined;
+  /** The items of the sidebar associated with the current doc. */
+  sidebarItems: PropSidebar | undefined;
+} {
+  const location = useLocation();
+  const docRoutes = route.routes!;
+  const currentDocRoute = docRoutes.find((docRoute) =>
+    matchPath(location.pathname, docRoute),
+  );
+  if (!currentDocRoute) {
+    return null;
+  }
+
+  // For now, the sidebarName is added as route config: not ideal!
+  const sidebarName = currentDocRoute.sidebar as string;
+
+  const sidebarItems = sidebarName
+    ? versionMetadata.docsSidebars[sidebarName]
+    : undefined;
+
+  const docElement = renderRoutes(docRoutes);
+
+  return {
+    docElement,
+    sidebarName,
+    sidebarItems,
+  };
+}

package/src/utils/footerUtils.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {MultiColumnFooter, SimpleFooter} from './useThemeConfig';
+
+/**
+ * A rough duck-typing about whether the `footer.links` is intended to be multi-
+ * column.
+ */
+export function isMultiColumnFooterLinks(
+  links: MultiColumnFooter['links'] | SimpleFooter['links'],
+): links is MultiColumnFooter['links'] {
+  return 'title' in links[0]!;
+}

package/src/utils/generalUtils.ts

@@ -4,12 +4,16 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
-export const useTitleFormatter = (title?: string | undefined): string => {
-  const {siteConfig = {}} = useDocusaurusContext();
-  const {title: siteTitle, titleDelimiter = '|'} = siteConfig;
-  return title && title.trim().length
+/**
+ * Formats the page's title based on relevant site config and other contexts.
+ */
+export function useTitleFormatter(title?: string | undefined): string {
+  const {siteConfig} = useDocusaurusContext();
+  const {title: siteTitle, titleDelimiter} = siteConfig;
+  return title?.trim().length
     ? `${title.trim()} ${titleDelimiter} ${siteTitle}`
     : siteTitle;
-};
+}

package/src/utils/historyUtils.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {useEffect} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {useEvent} from './reactUtils';
+import type {Location, Action} from 'history';
+
+type HistoryBlockHandler = (location: Location, action: Action) => void | false;
+
+/**
+ * Permits to register a handler that will be called on history actions (pop,
+ * push, replace). If the handler returns `false`, the navigation transition
+ * will be blocked/cancelled.
+ */
+function useHistoryActionHandler(handler: HistoryBlockHandler): void {
+  const history = useHistory();
+  const stableHandler = useEvent(handler);
+  useEffect(
+    // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
+    () => history.block((location, action) => stableHandler(location, action)),
+    [history, stableHandler],
+  );
+}
+
+/**
+ * Permits to register a handler that will be called on history pop navigation
+ * (backward/forward). If the handler returns `false`, the backward/forward
+ * transition will be blocked. Unfortunately there's no good way to detect the
+ * "direction" (backward/forward) of the POP event.
+ */
+export function useHistoryPopHandler(handler: HistoryBlockHandler): void {
+  useHistoryActionHandler((location, action) => {
+    if (action === 'POP') {
+      // Maybe block navigation if handler returns false
+      return handler(location, action);
+    }
+    // Don't block other navigation actions
+    return undefined;
+  });
+}

package/src/utils/jsUtils.ts

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// A replacement of lodash in client code
+
+/**
+ * Gets the duplicate values in an array.
+ * @param arr The array.
+ * @param comparator Compares two values and returns `true` if they are equal
+ * (duplicated).
+ * @returns Value of the elements `v` that have a preceding element `u` where
+ * `comparator(u, v) === true`. Values within the returned array are not
+ * guaranteed to be unique.
+ */
+export function duplicates<T>(
+  arr: readonly T[],
+  comparator: (a: T, b: T) => boolean = (a, b) => a === b,
+): T[] {
+  return arr.filter(
+    (v, vIndex) => arr.findIndex((u) => comparator(u, v)) !== vIndex,
+  );
+}
+
+/**
+ * Remove duplicate array items (similar to `_.uniq`)
+ * @param arr The array.
+ * @returns An array with duplicate elements removed by reference comparison.
+ */
+export function uniq<T>(arr: T[]): T[] {
+  // Note: had problems with [...new Set()]: https://github.com/facebook/docusaurus/issues/4972#issuecomment-863895061
+  return Array.from(new Set(arr));
+}

package/src/utils/metadataUtils.tsx

@@ -0,0 +1,115 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, {type ReactNode} from 'react';
+import clsx from 'clsx';
+import Head from '@docusaurus/Head';
+import useRouteContext from '@docusaurus/useRouteContext';
+import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
+import {useTitleFormatter} from './generalUtils';
+
+type PageMetadataProps = {
+  readonly title?: string;
+  readonly description?: string;
+  readonly keywords?: readonly string[] | string;
+  readonly image?: string;
+  readonly children?: ReactNode;
+};
+
+/**
+ * Helper component to manipulate page metadata and override site defaults.
+ * Works in the same way as Helmet.
+ */
+export function PageMetadata({
+  title,
+  description,
+  keywords,
+  image,
+  children,
+}: PageMetadataProps): JSX.Element {
+  const pageTitle = useTitleFormatter(title);
+  const {withBaseUrl} = useBaseUrlUtils();
+  const pageImage = image ? withBaseUrl(image, {absolute: true}) : undefined;
+
+  return (
+    <Head>
+      {title && <title>{pageTitle}</title>}
+      {title && <meta property="og:title" content={pageTitle} />}
+
+      {description && <meta name="description" content={description} />}
+      {description && <meta property="og:description" content={description} />}
+
+      {keywords && (
+        <meta
+          name="keywords"
+          content={
+            // https://github.com/microsoft/TypeScript/issues/17002
+            (Array.isArray(keywords) ? keywords.join(',') : keywords) as string
+          }
+        />
+      )}
+
+      {pageImage && <meta property="og:image" content={pageImage} />}
+      {pageImage && <meta name="twitter:image" content={pageImage} />}
+
+      {children}
+    </Head>
+  );
+}
+
+const HtmlClassNameContext = React.createContext<string | undefined>(undefined);
+
+/**
+ * Every layer of this provider will append a class name to the HTML element.
+ * There's no consumer for this hook: it's side-effect-only. This wrapper is
+ * necessary because Helmet does not "merge" classes.
+ * @see https://github.com/staylor/react-helmet-async/issues/161
+ */
+export function HtmlClassNameProvider({
+  className: classNameProp,
+  children,
+}: {
+  className: string;
+  children: ReactNode;
+}): JSX.Element {
+  const classNameContext = React.useContext(HtmlClassNameContext);
+  const className = clsx(classNameContext, classNameProp);
+  return (
+    <HtmlClassNameContext.Provider value={className}>
+      <Head>
+        <html className={className} />
+      </Head>
+      {children}
+    </HtmlClassNameContext.Provider>
+  );
+}
+
+function pluginNameToClassName(pluginName: string) {
+  return `plugin-${pluginName.replace(
+    /docusaurus-(?:plugin|theme)-(?:content-)?/gi,
+    '',
+  )}`;
+}
+
+/**
+ * A very thin wrapper around `HtmlClassNameProvider` that adds the plugin ID +
+ * name to the HTML class name.
+ */
+export function PluginHtmlClassNameProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const routeContext = useRouteContext();
+  const nameClass = pluginNameToClassName(routeContext.plugin.name);
+  const idClass = `plugin-id-${routeContext.plugin.id}`;
+  return (
+    <HtmlClassNameProvider className={clsx(nameClass, idClass)}>
+      {children}
+    </HtmlClassNameProvider>
+  );
+}

package/src/utils/navbarUtils.tsx

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React, {type ReactNode} from 'react';
+import {NavbarMobileSidebarProvider} from '../contexts/navbarMobileSidebar';
+import {NavbarSecondaryMenuContentProvider} from '../contexts/navbarSecondaryMenu/content';
+import {NavbarSecondaryMenuDisplayProvider} from '../contexts/navbarSecondaryMenu/display';
+
+const DefaultNavItemPosition = 'right';
+
+/**
+ * Split links by left/right. If position is unspecified, fallback to right.
+ */
+export function splitNavbarItems<T extends {position?: 'left' | 'right'}>(
+  items: T[],
+): [leftItems: T[], rightItems: T[]] {
+  function isLeft(item: T): boolean {
+    return (item.position ?? DefaultNavItemPosition) === 'left';
+  }
+
+  const leftItems = items.filter(isLeft);
+  const rightItems = items.filter((item) => !isLeft(item));
+
+  return [leftItems, rightItems];
+}
+
+/**
+ * Composes multiple navbar state providers that are mutually dependent and
+ * hence can't be re-ordered.
+ */
+export function NavbarProvider({children}: {children: ReactNode}): JSX.Element {
+  return (
+    <NavbarSecondaryMenuContentProvider>
+      <NavbarMobileSidebarProvider>
+        <NavbarSecondaryMenuDisplayProvider>
+          {children}
+        </NavbarSecondaryMenuDisplayProvider>
+      </NavbarMobileSidebarProvider>
+    </NavbarSecondaryMenuContentProvider>
+  );
+}