@docusaurus/theme-common 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/src/utils/scrollUtils.tsx

@@ -0,0 +1,238 @@
+/**
+ * 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, {
+  createContext,
+  ReactNode,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from 'react';
+import {useDynamicCallback} from './reactUtils';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+/**
+ * We need a way to update the scroll position while ignoring scroll events
+ * without affecting Navbar/BackToTop visibility
+ *
+ * This API permits to temporarily disable/ignore scroll events
+ * Motivated by https://github.com/facebook/docusaurus/pull/5618
+ */
+type ScrollController = {
+  /**
+   * A boolean ref tracking whether scroll events are enabled
+   */
+  scrollEventsEnabledRef: React.MutableRefObject<boolean>;
+  /**
+   * Enables scroll events in `useScrollPosition`
+   */
+  enableScrollEvents: () => void;
+  /**
+   * Disables scroll events in `useScrollPosition`
+   */
+  disableScrollEvents: () => void;
+};
+
+function useScrollControllerContextValue(): ScrollController {
+  const scrollEventsEnabledRef = useRef(true);
+
+  return useMemo(
+    () => ({
+      scrollEventsEnabledRef,
+      enableScrollEvents: () => {
+        scrollEventsEnabledRef.current = true;
+      },
+      disableScrollEvents: () => {
+        scrollEventsEnabledRef.current = false;
+      },
+    }),
+    [],
+  );
+}
+
+const ScrollMonitorContext = createContext<ScrollController | undefined>(
+  undefined,
+);
+
+export function ScrollControllerProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <ScrollMonitorContext.Provider value={useScrollControllerContextValue()}>
+      {children}
+    </ScrollMonitorContext.Provider>
+  );
+}
+
+export function useScrollController(): ScrollController {
+  const context = useContext(ScrollMonitorContext);
+  if (context == null) {
+    throw new Error(
+      '"useScrollController" is used but no context provider was found in the React tree.',
+    );
+  }
+  return context;
+}
+
+const getScrollPosition = (): ScrollPosition | null => {
+  return ExecutionEnvironment.canUseDOM
+    ? {
+        scrollX: window.pageXOffset,
+        scrollY: window.pageYOffset,
+      }
+    : null;
+};
+
+type ScrollPosition = {scrollX: number; scrollY: number};
+
+export function useScrollPosition(
+  effect: (
+    position: ScrollPosition,
+    lastPosition: ScrollPosition | null,
+  ) => void,
+  deps: unknown[] = [],
+): void {
+  const {scrollEventsEnabledRef} = useScrollController();
+  const lastPositionRef = useRef<ScrollPosition | null>(getScrollPosition());
+
+  const dynamicEffect = useDynamicCallback(effect);
+
+  useEffect(() => {
+    const handleScroll = () => {
+      if (!scrollEventsEnabledRef.current) {
+        return;
+      }
+      const currentPosition = getScrollPosition()!;
+
+      if (dynamicEffect) {
+        dynamicEffect(currentPosition, lastPositionRef.current);
+      }
+
+      lastPositionRef.current = currentPosition;
+    };
+
+    const opts: AddEventListenerOptions & EventListenerOptions = {
+      passive: true,
+    };
+
+    handleScroll();
+    window.addEventListener('scroll', handleScroll, opts);
+
+    return () => window.removeEventListener('scroll', handleScroll, opts);
+  }, [
+    dynamicEffect,
+    scrollEventsEnabledRef,
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    ...deps,
+  ]);
+}
+
+type UseScrollPositionSaver = {
+  /**
+   * Measure the top of an element, and store the details
+   */
+  save: (elem: HTMLElement) => void;
+  /**
+   * Restore the page position to keep the stored element's position from
+   * the top of the viewport, and remove the stored details
+   */
+  restore: () => {restored: boolean};
+};
+
+function useScrollPositionSaver(): UseScrollPositionSaver {
+  const lastElementRef = useRef<{elem: HTMLElement | null; top: number}>({
+    elem: null,
+    top: 0,
+  });
+
+  const save = useCallback((elem: HTMLElement) => {
+    lastElementRef.current = {
+      elem,
+      top: elem.getBoundingClientRect().top,
+    };
+  }, []);
+
+  const restore = useCallback(() => {
+    const {
+      current: {elem, top},
+    } = lastElementRef;
+    if (!elem) {
+      return {restored: false};
+    }
+    const newTop = elem.getBoundingClientRect().top;
+    const heightDiff = newTop - top;
+    if (heightDiff) {
+      window.scrollBy({left: 0, top: heightDiff});
+    }
+    lastElementRef.current = {elem: null, top: 0};
+
+    return {restored: heightDiff !== 0};
+  }, []);
+
+  return useMemo(() => ({save, restore}), [restore, save]);
+}
+
+type UseScrollPositionBlockerReturn = {
+  blockElementScrollPositionUntilNextRender: (el: HTMLElement) => void;
+};
+
+/**
+ * This hook permits to "block" the scroll position of a dom element
+ * The idea is that we should be able to update DOM content above this element
+ * but the screen position of this element should not change
+ *
+ * Feature motivated by the Tabs groups:
+ * clicking on a tab may affect tabs of the same group upper in the tree
+ * Yet to avoid a bad UX, the clicked tab must remain under the user mouse!
+ * See GIF here: https://github.com/facebook/docusaurus/pull/5618
+ */
+export function useScrollPositionBlocker(): UseScrollPositionBlockerReturn {
+  const scrollController = useScrollController();
+  const scrollPositionSaver = useScrollPositionSaver();
+
+  const nextLayoutEffectCallbackRef = useRef<(() => void) | undefined>(
+    undefined,
+  );
+
+  const blockElementScrollPositionUntilNextRender = useCallback(
+    (el: HTMLElement) => {
+      scrollPositionSaver.save(el);
+      scrollController.disableScrollEvents();
+      nextLayoutEffectCallbackRef.current = () => {
+        const {restored} = scrollPositionSaver.restore();
+        nextLayoutEffectCallbackRef.current = undefined;
+
+        // Restoring the former scroll position will trigger a scroll event
+        // We need to wait for next scroll event to happen
+        // before enabling again the scrollController events
+        if (restored) {
+          const handleScrollRestoreEvent = () => {
+            scrollController.enableScrollEvents();
+            window.removeEventListener('scroll', handleScrollRestoreEvent);
+          };
+          window.addEventListener('scroll', handleScrollRestoreEvent);
+        } else {
+          scrollController.enableScrollEvents();
+        }
+      };
+    },
+    [scrollController, scrollPositionSaver],
+  );
+
+  useLayoutEffect(() => {
+    nextLayoutEffectCallbackRef.current?.();
+  });
+
+  return {
+    blockElementScrollPositionUntilNextRender,
+  };
+}

package/src/utils/storageUtils.ts

@@ -27,7 +27,7 @@ function getBrowserStorage(
     try {
       return window[storageType];
     } catch (e) {
-      logOnceBrowserStorageNotAvailableWarning(e);
+      logOnceBrowserStorageNotAvailableWarning(e as Error);
       return null;
     }
   }

package/src/utils/tagsUtils.ts

@@ -0,0 +1,48 @@
+/**
+ * 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 {translate} from '@docusaurus/Translate';
+
+export const translateTagsPageTitle = (): string =>
+  translate({
+    id: 'theme.tags.tagsPageTitle',
+    message: 'Tags',
+    description: 'The title of the tag list page',
+  });
+
+type TagsListItem = Readonly<{name: string; permalink: string; count: number}>; // TODO remove duplicated type :s
+
+export type TagLetterEntry = Readonly<{letter: string; tags: TagsListItem[]}>;
+
+function getTagLetter(tag: string): string {
+  return tag[0].toUpperCase();
+}
+
+export function listTagsByLetters(
+  tags: readonly TagsListItem[],
+): TagLetterEntry[] {
+  // Group by letters
+  const groups: Record<string, TagsListItem[]> = {};
+  Object.values(tags).forEach((tag) => {
+    const letter = getTagLetter(tag.name);
+    groups[letter] = groups[letter] ?? [];
+    groups[letter].push(tag);
+  });
+
+  return (
+    Object.entries(groups)
+      // Sort letters
+      .sort(([letter1], [letter2]) => letter1.localeCompare(letter2))
+      .map(([letter, letterTags]) => {
+        // Sort tags inside a letter
+        const sortedTags = letterTags.sort((tag1, tag2) =>
+          tag1.name.localeCompare(tag2.name),
+        );
+        return {letter, tags: sortedTags};
+      })
+  );
+}

package/src/utils/tocUtils.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 {TOCItem} from '@docusaurus/types';
+
+type FilterTOCParam = {
+  toc: readonly TOCItem[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+};
+
+export function filterTOC({
+  toc,
+  minHeadingLevel,
+  maxHeadingLevel,
+}: FilterTOCParam): TOCItem[] {
+  function isValid(item: TOCItem) {
+    return item.level >= minHeadingLevel && item.level <= maxHeadingLevel;
+  }
+
+  return toc.flatMap((item) => {
+    const filteredChildren = filterTOC({
+      toc: item.children,
+      minHeadingLevel,
+      maxHeadingLevel,
+    });
+    if (isValid(item)) {
+      return [
+        {
+          ...item,
+          children: filteredChildren,
+        },
+      ];
+    } else {
+      return filteredChildren;
+    }
+  });
+}
+
+// Memoize potentially expensive filtering logic
+export function useTOCFilter({
+  toc,
+  minHeadingLevel,
+  maxHeadingLevel,
+}: FilterTOCParam): readonly TOCItem[] {
+  return useMemo(() => {
+    return filterTOC({toc, minHeadingLevel, maxHeadingLevel});
+  }, [toc, minHeadingLevel, maxHeadingLevel]);
+}

package/src/utils/useAlternatePageUtils.ts

@@ -11,7 +11,15 @@ import {useLocation} from '@docusaurus/router';
 // Permits to obtain the url of the current page in another locale
 // Useful to generate hreflang meta headers etc...
 // See https://developers.google.com/search/docs/advanced/crawling/localized-versions
-export function useAlternatePageUtils() {
+export function useAlternatePageUtils(): {
+  createUrl: ({
+    locale,
+    fullyQualified,
+  }: {
+    locale: string;
+    fullyQualified: boolean;
+  }) => string;
+} {
   const {
     siteConfig: {baseUrl, url},
     i18n: {defaultLocale, currentLocale},

package/src/utils/useLocalPathname.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useLocation} from '@docusaurus/router';
+
+// Get the pathname of current route, without the optional site baseUrl
+// - /docs/myDoc => /docs/myDoc
+// - /baseUrl/docs/myDoc => /docs/myDoc
+export function useLocalPathname(): string {
+  const {
+    siteConfig: {baseUrl},
+  } = useDocusaurusContext();
+  const {pathname} = useLocation();
+  return pathname.replace(baseUrl, '/');
+}

package/src/utils/useLocationChange.ts

@@ -5,10 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useEffect, useRef} from 'react';
+import {useEffect} from 'react';
 import {useLocation} from '@docusaurus/router';
 import {Location} from '@docusaurus/history';
 import {usePrevious} from './usePrevious';
+import {useDynamicCallback} from './reactUtils';
 
 type LocationChangeEvent = {
   location: Location;
@@ -20,18 +21,13 @@ type OnLocationChange = (locationChangeEvent: LocationChangeEvent) => void;
 export function useLocationChange(onLocationChange: OnLocationChange): void {
   const location = useLocation();
   const previousLocation = usePrevious(location);
-  const isFirst = useRef<boolean>(true);
 
-  useEffect(() => {
-    // Prevent first effect to trigger the listener on mount
-    if (isFirst.current) {
-      isFirst.current = false;
-      return;
-    }
+  const onLocationChangeDynamic = useDynamicCallback(onLocationChange);
 
-    onLocationChange({
+  useEffect(() => {
+    onLocationChangeDynamic({
       location,
       previousLocation,
     });
-  }, [location]);
+  }, [onLocationChangeDynamic, location, previousLocation]);
 }

package/src/utils/usePluralForm.ts

@@ -107,7 +107,9 @@ function selectPluralMessage(
   }
 }
 
-export function usePluralForm() {
+export function usePluralForm(): {
+  selectMessage: (count: number, pluralMessages: string) => string;
+} {
   const localePluralForm = useLocalePluralForms();
   return {
     selectMessage: (count: number, pluralMessages: string): string => {

package/src/utils/usePrevious.ts

@@ -5,12 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useRef, useEffect} from 'react';
+import {useRef} from 'react';
+import {useIsomorphicLayoutEffect} from './reactUtils';
 
 export function usePrevious<T>(value: T): T | undefined {
   const ref = useRef<T>();
 
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     ref.current = value;
   });
 

package/src/utils/useTOCHighlight.ts

@@ -0,0 +1,179 @@
+/**
+ * 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 './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 (ie, 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;
+}) {
+  const selectors = [];
+  for (let i = minHeadingLevel; i <= maxHeadingLevel; i += 1) {
+    selectors.push(`h${i}.anchor`);
+  }
+
+  return Array.from(
+    document.querySelectorAll(selectors.join()),
+  ) as HTMLElement[];
+}
+
+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
+  // Note: 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
+    else {
+      // 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? (ie we are at the bottom of the page)
+  // => highlight the last anchor found
+  else {
+    return anchors[anchors.length - 1];
+  }
+}
+
+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 = {
+  linkClassName: string;
+  linkActiveClassName: string;
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+};
+
+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;
+      } 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]);
+}
+
+export default useTOCHighlight;

package/src/utils/useThemeConfig.ts

@@ -7,6 +7,7 @@
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {PrismTheme} from 'prism-react-renderer';
 import {CSSProperties} from 'react';
+import {DeepPartial} from 'utility-types';
 
 export type DocsVersionPersistence = 'localStorage' | 'none';
 
@@ -16,11 +17,13 @@ export type NavbarItem = {
   items?: NavbarItem[];
   label?: string;
   position?: 'left' | 'right';
-};
+} & Record<string, unknown>;
 
 export type NavbarLogo = {
   src: string;
   srcDark?: string;
+  width?: string | number;
+  height?: string | number;
   href?: string;
   target?: string;
   alt?: string;
@@ -79,12 +82,20 @@ export type Footer = {
     alt?: string;
     src?: string;
     srcDark?: string;
+    width?: string | number;
+    height?: string | number;
     href?: string;
   };
   copyright?: string;
   links: FooterLinks[];
 };
 
+export type TableOfContents = {
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+};
+
+// Theme config after validation/normalization
 export type ThemeConfig = {
   docs: {
     versionPersistence: DocsVersionPersistence;
@@ -101,10 +112,15 @@ export type ThemeConfig = {
   prism: PrismConfig;
   footer?: Footer;
   hideableSidebar: boolean;
-  image: string;
+  image?: string;
   metadatas: Array<Record<string, string>>;
+  sidebarCollapsible: boolean;
+  tableOfContents: TableOfContents;
 };
 
+// User-provided theme config, unnormalized
+export type UserThemeConfig = DeepPartial<ThemeConfig>;
+
 export function useThemeConfig(): ThemeConfig {
   return useDocusaurusContext().siteConfig.themeConfig as ThemeConfig;
 }