@docusaurus/theme-common 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/hooks/useLockBodyScroll.ts

@@ -0,0 +1,21 @@
+/**
+ * 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';
+
+/**
+ * Side-effect that locks the document body's scroll throughout the lifetime of
+ * the containing component. e.g. when the mobile sidebar is expanded.
+ */
+export function useLockBodyScroll(lock: boolean = true): void {
+  useEffect(() => {
+    document.body.style.overflow = lock ? 'hidden' : 'visible';
+    return () => {
+      document.body.style.overflow = 'visible';
+    };
+  }, [lock]);
+}

package/src/hooks/useMutationObserver.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 {useEvent, useShallowMemoObject} from '../utils/reactUtils';
+
+type Options = MutationObserverInit;
+
+const DefaultOptions: Options = {
+  attributes: true,
+  characterData: true,
+  childList: true,
+  subtree: true,
+};
+
+export function useMutationObserver(
+  target: Element | undefined | null,
+  callback: MutationCallback,
+  options: Options = DefaultOptions,
+): void {
+  const stableCallback = useEvent(callback);
+
+  // MutationObserver options are not nested much
+  // so this should be to memo options in 99%
+  // TODO handle options.attributeFilter array
+  const stableOptions: Options = useShallowMemoObject(options);
+
+  useEffect(() => {
+    const observer = new MutationObserver(stableCallback);
+    if (target) {
+      observer.observe(target, stableOptions);
+    }
+    return () => observer.disconnect();
+  }, [target, stableCallback, stableOptions]);
+}

package/src/hooks/usePrismTheme.ts

@@ -0,0 +1,24 @@
+/**
+ * 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 {useColorMode} from '../contexts/colorMode';
+import {useThemeConfig} from '../utils/useThemeConfig';
+import type {PrismTheme} from 'prism-react-renderer';
+
+/**
+ * Returns a color-mode-dependent Prism theme: whatever the user specified in
+ * the config. Falls back to `palenight`.
+ */
+export function usePrismTheme(): PrismTheme {
+  const {prism} = useThemeConfig();
+  const {colorMode} = useColorMode();
+  const lightModeTheme = prism.theme;
+  const darkModeTheme = prism.darkTheme || lightModeTheme;
+  const prismTheme = colorMode === 'dark' ? darkModeTheme : lightModeTheme;
+
+  return prismTheme;
+}

package/src/hooks/useSearchPage.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 {useCallback, useEffect, useState} from 'react';
+import {useHistory} from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+const SEARCH_PARAM_QUERY = 'q';
+
+/** Some utility functions around search queries. */
+export function useSearchPage(): {
+  /**
+   * Works hand-in-hand with `setSearchQuery`; whatever the user has inputted
+   * into the search box.
+   */
+  searchQuery: string;
+  /**
+   * Set a new search query. In addition to updating `searchQuery`, this handle
+   * also mutates the location and appends the query.
+   */
+  setSearchQuery: (newSearchQuery: string) => void;
+  /**
+   * Given a query, this handle generates the corresponding search page link,
+   * with base URL prepended.
+   */
+  generateSearchPageLink: (targetSearchQuery: string) => string;
+} {
+  const history = useHistory();
+  const {
+    siteConfig: {baseUrl},
+  } = useDocusaurusContext();
+
+  const [searchQuery, setSearchQueryState] = useState('');
+
+  // Init search query just after React hydration
+  useEffect(() => {
+    const searchQueryStringValue =
+      new URLSearchParams(window.location.search).get(SEARCH_PARAM_QUERY) ?? '';
+
+    setSearchQueryState(searchQueryStringValue);
+  }, []);
+
+  const setSearchQuery = useCallback(
+    (newSearchQuery: string) => {
+      const searchParams = new URLSearchParams(window.location.search);
+
+      if (newSearchQuery) {
+        searchParams.set(SEARCH_PARAM_QUERY, newSearchQuery);
+      } else {
+        searchParams.delete(SEARCH_PARAM_QUERY);
+      }
+
+      history.replace({
+        search: searchParams.toString(),
+      });
+      setSearchQueryState(newSearchQuery);
+    },
+    [history],
+  );
+
+  const generateSearchPageLink = useCallback(
+    (targetSearchQuery: string) =>
+      // Refer to https://github.com/facebook/docusaurus/pull/2838
+      `${baseUrl}search?${SEARCH_PARAM_QUERY}=${encodeURIComponent(
+        targetSearchQuery,
+      )}`,
+    [baseUrl],
+  );
+
+  return {
+    searchQuery,
+    setSearchQuery,
+    generateSearchPageLink,
+  };
+}

package/src/hooks/useSkipToContent.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 React from 'react';
+import {useCallback, useRef} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {useLocationChange} from '../utils/useLocationChange';
+import {ThemeClassNames} from '../utils/ThemeClassNames';
+
+function programmaticFocus(el: HTMLElement) {
+  el.setAttribute('tabindex', '-1');
+  el.focus();
+  el.removeAttribute('tabindex');
+}
+
+/** This hook wires the logic for a skip-to-content link. */
+export function useSkipToContent(): {
+  /**
+   * The ref to the container. On page transition, the container will be focused
+   * so that keyboard navigators can instantly interact with the link and jump
+   * to content. **Note:** the type is `RefObject<HTMLDivElement>` only because
+   * the typing for refs don't reflect that the `ref` prop is contravariant, so
+   * using `HTMLElement` causes type-checking to fail. You can plug the ref into
+   * any HTML element, as long as it can be focused.
+   */
+  containerRef: React.RefObject<HTMLDivElement>;
+  /**
+   * Callback fired when the skip to content link has been interacted with. It
+   * will programmatically focus the main content.
+   */
+  handleSkip: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+} {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const {action} = useHistory();
+  const handleSkip = useCallback((e: React.MouseEvent<HTMLAnchorElement>) => {
+    e.preventDefault();
+
+    const targetElement: HTMLElement | null =
+      document.querySelector('main:first-of-type') ??
+      document.querySelector(`.${ThemeClassNames.wrapper.main}`);
+
+    if (targetElement) {
+      programmaticFocus(targetElement);
+    }
+  }, []);
+
+  useLocationChange(({location}) => {
+    if (containerRef.current && !location.hash && action === 'PUSH') {
+      programmaticFocus(containerRef.current);
+    }
+  });
+
+  return {containerRef, handleSkip};
+}

package/src/hooks/useTOCHighlight.ts

@@ -0,0 +1,189 @@
+/**
+ * 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, useRef} from 'react';
+import {useThemeConfig} from '../utils/useThemeConfig';
+
+// TODO make the hardcoded theme-classic classnames configurable (or add them
+// to ThemeClassNames?)
+
+/**
+ * If the anchor has no height and is just a "marker" in the DOM; we'll use the
+ * parent (normally the link text) rect boundaries instead
+ */
+function getVisibleBoundingClientRect(element: HTMLElement): DOMRect {
+  const rect = element.getBoundingClientRect();
+  const hasNoHeight = rect.top === rect.bottom;
+  if (hasNoHeight) {
+    return getVisibleBoundingClientRect(element.parentNode as HTMLElement);
+  }
+  return rect;
+}
+
+/**
+ * Considering we divide viewport into 2 zones of each 50vh, this returns true
+ * if an element is in the first zone (i.e., appear in viewport, near the top)
+ */
+function isInViewportTopHalf(boundingRect: DOMRect) {
+  return boundingRect.top > 0 && boundingRect.bottom < window.innerHeight / 2;
+}
+
+function getAnchors({
+  minHeadingLevel,
+  maxHeadingLevel,
+}: {
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): HTMLElement[] {
+  const selectors = [];
+  for (let i = minHeadingLevel; i <= maxHeadingLevel; i += 1) {
+    selectors.push(`h${i}.anchor`);
+  }
+  return Array.from(document.querySelectorAll(selectors.join()));
+}
+
+function getActiveAnchor(
+  anchors: HTMLElement[],
+  {
+    anchorTopOffset,
+  }: {
+    anchorTopOffset: number;
+  },
+): Element | null {
+  // Naming is hard: The "nextVisibleAnchor" is the first anchor that appear
+  // under the viewport top boundary. It does not mean this anchor is visible
+  // yet, but if user continues scrolling down, it will be the first to become
+  // visible
+  const nextVisibleAnchor = anchors.find((anchor) => {
+    const boundingRect = getVisibleBoundingClientRect(anchor);
+    return boundingRect.top >= anchorTopOffset;
+  });
+
+  if (nextVisibleAnchor) {
+    const boundingRect = getVisibleBoundingClientRect(nextVisibleAnchor);
+    // If anchor is in the top half of the viewport: it is the one we consider
+    // "active" (unless it's too close to the top and and soon to be scrolled
+    // outside viewport)
+    if (isInViewportTopHalf(boundingRect)) {
+      return nextVisibleAnchor;
+    }
+    // If anchor is in the bottom half of the viewport, or under the viewport,
+    // we consider the active anchor is the previous one. This is because the
+    // main text appearing in the user screen mostly belong to the previous
+    // anchor. Returns null for the first anchor, see
+    // https://github.com/facebook/docusaurus/issues/5318
+    return anchors[anchors.indexOf(nextVisibleAnchor) - 1] ?? null;
+  }
+  // No anchor under viewport top (i.e. we are at the bottom of the page),
+  // highlight the last anchor found
+  return anchors[anchors.length - 1] ?? null;
+}
+
+function getLinkAnchorValue(link: HTMLAnchorElement): string {
+  return decodeURIComponent(link.href.substring(link.href.indexOf('#') + 1));
+}
+
+function getLinks(linkClassName: string) {
+  return Array.from(
+    document.getElementsByClassName(linkClassName),
+  ) as HTMLAnchorElement[];
+}
+
+function getNavbarHeight(): number {
+  // Not ideal to obtain actual height this way
+  // Using TS ! (not ?) because otherwise a bad selector would be un-noticed
+  return document.querySelector('.navbar')!.clientHeight;
+}
+
+function useAnchorTopOffsetRef() {
+  const anchorTopOffsetRef = useRef<number>(0);
+  const {
+    navbar: {hideOnScroll},
+  } = useThemeConfig();
+
+  useEffect(() => {
+    anchorTopOffsetRef.current = hideOnScroll ? 0 : getNavbarHeight();
+  }, [hideOnScroll]);
+
+  return anchorTopOffsetRef;
+}
+
+export type TOCHighlightConfig = {
+  /** A class name that all TOC links share. */
+  linkClassName: string;
+  /** The class name applied to the active (highlighted) link. */
+  linkActiveClassName: string;
+  /**
+   * The minimum heading level that the TOC includes. Only headings that are in
+   * this range will be eligible as "active heading".
+   */
+  minHeadingLevel: number;
+  /** @see {@link TOCHighlightConfig.minHeadingLevel} */
+  maxHeadingLevel: number;
+};
+
+/**
+ * Side-effect that applies the active class name to the TOC heading that the
+ * user is currently viewing. Disabled when `config` is undefined.
+ */
+export function useTOCHighlight(config: TOCHighlightConfig | undefined): void {
+  const lastActiveLinkRef = useRef<HTMLAnchorElement | undefined>(undefined);
+
+  const anchorTopOffsetRef = useAnchorTopOffsetRef();
+
+  useEffect(() => {
+    if (!config) {
+      // No-op, highlighting is disabled
+      return () => {};
+    }
+
+    const {
+      linkClassName,
+      linkActiveClassName,
+      minHeadingLevel,
+      maxHeadingLevel,
+    } = config;
+
+    function updateLinkActiveClass(link: HTMLAnchorElement, active: boolean) {
+      if (active) {
+        if (lastActiveLinkRef.current && lastActiveLinkRef.current !== link) {
+          lastActiveLinkRef.current.classList.remove(linkActiveClassName);
+        }
+        link.classList.add(linkActiveClassName);
+        lastActiveLinkRef.current = link;
+        // link.scrollIntoView({block: 'nearest'});
+      } else {
+        link.classList.remove(linkActiveClassName);
+      }
+    }
+
+    function updateActiveLink() {
+      const links = getLinks(linkClassName);
+      const anchors = getAnchors({minHeadingLevel, maxHeadingLevel});
+      const activeAnchor = getActiveAnchor(anchors, {
+        anchorTopOffset: anchorTopOffsetRef.current,
+      });
+      const activeLink = links.find(
+        (link) => activeAnchor && activeAnchor.id === getLinkAnchorValue(link),
+      );
+
+      links.forEach((link) => {
+        updateLinkActiveClass(link, link === activeLink);
+      });
+    }
+
+    document.addEventListener('scroll', updateActiveLink);
+    document.addEventListener('resize', updateActiveLink);
+
+    updateActiveLink();
+
+    return () => {
+      document.removeEventListener('scroll', updateActiveLink);
+      document.removeEventListener('resize', updateActiveLink);
+    };
+  }, [config, anchorTopOffsetRef]);
+}

package/src/hooks/useWindowSize.ts

@@ -0,0 +1,72 @@
+/**
+ * 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, useState} from 'react';
+
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+const windowSizes = {
+  desktop: 'desktop',
+  mobile: 'mobile',
+  ssr: 'ssr',
+} as const;
+
+type WindowSize = keyof typeof windowSizes;
+
+const DesktopThresholdWidth = 996;
+
+function getWindowSize() {
+  if (!ExecutionEnvironment.canUseDOM) {
+    return windowSizes.ssr;
+  }
+  return window.innerWidth > DesktopThresholdWidth
+    ? windowSizes.desktop
+    : windowSizes.mobile;
+}
+
+const DevSimulateSSR = process.env.NODE_ENV === 'development' && true;
+
+/**
+ * Gets the current window size as an enum value. We don't want it to return the
+ * actual width value, so that it only re-renders once a breakpoint is crossed.
+ *
+ * It may return `"ssr"`, which is very important to handle hydration FOUC or
+ * layout shifts. You have to handle it explicitly upfront. On the server, you
+ * may need to render BOTH the mobile/desktop elements (and hide one of them
+ * with mediaquery). We don't return `undefined` on purpose, to make it more
+ * explicit.
+ *
+ * In development mode, this hook will still return `"ssr"` for one second, to
+ * catch potential layout shifts, similar to strict mode calling effects twice.
+ */
+export function useWindowSize(): WindowSize {
+  const [windowSize, setWindowSize] = useState<WindowSize>(() => {
+    if (DevSimulateSSR) {
+      return 'ssr';
+    }
+    return getWindowSize();
+  });
+
+  useEffect(() => {
+    function updateWindowSize() {
+      setWindowSize(getWindowSize());
+    }
+
+    const timeout = DevSimulateSSR
+      ? window.setTimeout(updateWindowSize, 1000)
+      : undefined;
+
+    window.addEventListener('resize', updateWindowSize);
+
+    return () => {
+      window.removeEventListener('resize', updateWindowSize);
+      clearTimeout(timeout);
+    };
+  }, []);
+
+  return windowSize;
+}

package/src/index.ts

@@ -5,66 +5,73 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export {useThemeConfig} from './utils/useThemeConfig';
-
-export type {
-  ThemeConfig,
-  Navbar,
-  NavbarItem,
-  NavbarLogo,
-  Footer,
-  FooterLinks,
-  FooterLinkItem,
+/*
+ * APIs to document
+ */
+
+export {
+  useThemeConfig,
+  type ThemeConfig,
+  type UserThemeConfig,
+  type Navbar,
+  type NavbarItem,
+  type NavbarLogo,
+  type MultiColumnFooter,
+  type SimpleFooter,
+  type Footer,
+  type FooterLogo,
+  type FooterLinkItem,
+  type ColorModeConfig,
 } from './utils/useThemeConfig';
 
 export {createStorageSlot, listStorageKeys} from './utils/storageUtils';
 
-export {useAlternatePageUtils} from './utils/useAlternatePageUtils';
+export {useContextualSearchFilters} from './utils/searchUtils';
 
-export {parseCodeBlockTitle} from './utils/codeBlockUtils';
+export {useCurrentSidebarCategory} from './utils/docsUtils';
 
-export {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './utils/searchUtils';
+export {usePluralForm} from './utils/usePluralForm';
 
-export {isDocsPluginEnabled} from './utils/docsUtils';
+export {useCollapsible, Collapsible} from './components/Collapsible';
 
-export {isSamePath} from './utils/pathUtils';
+export {ThemeClassNames} from './utils/ThemeClassNames';
 
-export {useTitleFormatter} from './utils/generalUtils';
+export {
+  useIsomorphicLayoutEffect,
+  useEvent,
+  usePrevious,
+  composeProviders,
+  ReactContextError,
+} from './utils/reactUtils';
 
-export {usePluralForm} from './utils/usePluralForm';
+export {PageMetadata, HtmlClassNameProvider} from './utils/metadataUtils';
 
-export {useLocationChange} from './utils/useLocationChange';
+export {useColorMode, type ColorMode} from './contexts/colorMode';
 
-export {usePrevious} from './utils/usePrevious';
+export {
+  NavbarSecondaryMenuFiller,
+  type NavbarSecondaryMenuComponent,
+} from './contexts/navbarSecondaryMenu/content';
 
-export {useCollapsible, Collapsible} from './components/Collapsible';
-export type {
-  UseCollapsibleConfig,
-  UseCollapsibleReturns,
-} from './components/Collapsible';
+export {useWindowSize} from './hooks/useWindowSize';
 
-export {default as Details} from './components/Details';
-export type {DetailsProps} from './components/Details';
+/*
+ * APIs kept undocumented, on purpose
+ * Note: we still guarantee retro-compatibility on those
+ */
 
 export {
-  MobileSecondaryMenuProvider,
-  MobileSecondaryMenuFiller,
-  useMobileSecondaryMenuRenderer,
-} from './utils/mobileSecondaryMenu';
-export type {MobileSecondaryMenuComponent} from './utils/mobileSecondaryMenu';
+  translateTagsPageTitle,
+  listTagsByLetters,
+  type TagLetterEntry,
+} from './utils/tagsUtils';
 
-export {
-  useDocsPreferredVersion,
-  useDocsPreferredVersionByPluginId,
-} from './utils/docsPreferredVersion/useDocsPreferredVersion';
+export {isMultiColumnFooterLinks} from './utils/footerUtils';
 
-export {DocsPreferredVersionContextProvider} from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
+export {isRegexpStringMatch} from './utils/regexpUtils';
 
-export {ThemeClassNames} from './utils/ThemeClassNames';
+export {duplicates, uniq} from './utils/jsUtils';
 
-export {
-  AnnouncementBarProvider,
-  useAnnouncementBar,
-} from './utils/announcementBarUtils';
+export {usePrismTheme} from './hooks/usePrismTheme';
 
-export {useLocalPathname} from './utils/useLocalPathname';
+export {useDocsPreferredVersion} from './contexts/docsPreferredVersion';