@azerion/bunosaurus-theme-common 0.0.0-stage → 4.0.0

package/src/hooks/useBackToTopButton.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 {useRef, useState} from 'react';
+import {useScrollPosition, useSmoothScrollTo} from '../utils/scrollUtils';
+import {useLocationChange} from '../utils/useLocationChange';
+
+/** Wires the logic for the back to top button. */
+export function useBackToTopButton({
+  threshold,
+}: {
+  /**
+   * The minimum vertical scroll position, above which a scroll-up would not
+   * cause `shown` to become `true`. This is because BTT is only useful if the
+   * user is far down the page.
+   */
+  threshold: number;
+}): {
+  /**
+   * Whether the button should be displayed. We only show if the user has
+   * scrolled up and is on a vertical position greater than `threshold`.
+   */
+  shown: boolean;
+  /**
+   * A (memoized) handle for starting the scroll, which you can directly plug
+   * into the props.
+   */
+  scrollToTop: () => void;
+} {
+  const [shown, setShown] = useState(false);
+  const isFocusedAnchor = useRef(false);
+  const {startScroll, cancelScroll} = useSmoothScrollTo();
+
+  useScrollPosition(({scrollY: scrollTop}, lastPosition) => {
+    const lastScrollTop = lastPosition?.scrollY;
+    // Component is just being mounted. Not really a scroll event from the user.
+    // Ignore it.
+    if (!lastScrollTop) {
+      return;
+    }
+    if (isFocusedAnchor.current) {
+      // This scroll position change is triggered by navigating to an anchor.
+      // Ignore it.
+      isFocusedAnchor.current = false;
+    } else if (scrollTop >= lastScrollTop) {
+      // The user has scrolled down to "fight against" the animation. Cancel any
+      // animation under progress.
+      cancelScroll();
+      setShown(false);
+    } else if (scrollTop < threshold) {
+      // Scrolled to the minimum position; hide the button.
+      setShown(false);
+    } else if (
+      scrollTop + window.innerHeight <
+      document.documentElement.scrollHeight
+    ) {
+      setShown(true);
+    }
+  });
+
+  useLocationChange((locationChangeEvent) => {
+    if (locationChangeEvent.location.hash) {
+      isFocusedAnchor.current = true;
+      setShown(false);
+    }
+  });
+
+  return {shown, scrollToTop: () => startScroll(0)};
+}

package/src/hooks/useCodeWordWrap.ts

@@ -0,0 +1,107 @@
+/**
+ * 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 {RefObject} from 'react';
+import {useState, useCallback, useEffect, useRef} from 'react';
+import {useMutationObserver} from './useMutationObserver';
+
+// Callback fires when the "hidden" attribute of a tabpanel changes
+// See https://github.com/facebook/docusaurus/pull/7485
+function useTabBecameVisibleCallback(
+  codeBlockRef: RefObject<HTMLPreElement | null>,
+  callback: () => void,
+) {
+  const [hiddenTabElement, setHiddenTabElement] = useState<
+    Element | null | undefined
+  >();
+
+  const updateHiddenTabElement = useCallback(() => {
+    // No need to observe non-hidden tabs
+    // + we want to force a re-render when a tab becomes visible
+    setHiddenTabElement(
+      codeBlockRef.current?.closest('[role=tabpanel][hidden]'),
+    );
+  }, [codeBlockRef, setHiddenTabElement]);
+
+  useEffect(() => {
+    updateHiddenTabElement();
+  }, [updateHiddenTabElement]);
+
+  useMutationObserver(
+    hiddenTabElement,
+    (mutations: MutationRecord[]) => {
+      mutations.forEach((mutation) => {
+        if (
+          mutation.type === 'attributes' &&
+          mutation.attributeName === 'hidden'
+        ) {
+          callback();
+          updateHiddenTabElement();
+        }
+      });
+    },
+    {
+      attributes: true,
+      characterData: false,
+      childList: false,
+      subtree: false,
+    },
+  );
+}
+
+export type WordWrap = {
+  readonly codeBlockRef: RefObject<HTMLPreElement | null>;
+  readonly isEnabled: boolean;
+  readonly isCodeScrollable: boolean;
+  readonly toggle: () => void;
+};
+
+export function useCodeWordWrap(): WordWrap {
+  const [isEnabled, setIsEnabled] = useState(false);
+  const [isCodeScrollable, setIsCodeScrollable] = useState<boolean>(false);
+  const codeBlockRef = useRef<HTMLPreElement>(null);
+
+  const toggle = useCallback(() => {
+    const codeElement = codeBlockRef.current!.querySelector('code')!;
+
+    if (isEnabled) {
+      codeElement.removeAttribute('style');
+    } else {
+      codeElement.style.whiteSpace = 'pre-wrap';
+      // When code wrap is enabled, we want to avoid a scrollbar in any case
+      // Ensure that very very long words/strings/tokens still wrap
+      codeElement.style.overflowWrap = 'anywhere';
+    }
+
+    setIsEnabled((value) => !value);
+  }, [codeBlockRef, isEnabled]);
+
+  const updateCodeIsScrollable = useCallback(() => {
+    const {scrollWidth, clientWidth} = codeBlockRef.current!;
+    const isScrollable =
+      scrollWidth > clientWidth ||
+      codeBlockRef.current!.querySelector('code')!.hasAttribute('style');
+    setIsCodeScrollable(isScrollable);
+  }, [codeBlockRef]);
+
+  useTabBecameVisibleCallback(codeBlockRef, updateCodeIsScrollable);
+
+  useEffect(() => {
+    updateCodeIsScrollable();
+  }, [isEnabled, updateCodeIsScrollable]);
+
+  useEffect(() => {
+    window.addEventListener('resize', updateCodeIsScrollable, {
+      passive: true,
+    });
+
+    return () => {
+      window.removeEventListener('resize', updateCodeIsScrollable);
+    };
+  }, [updateCodeIsScrollable]);
+
+  return {codeBlockRef, isEnabled, isCodeScrollable, toggle};
+}

package/src/hooks/useHideableNavbar.ts

@@ -0,0 +1,81 @@
+/**
+ * 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 {useState, useCallback, useRef} from 'react';
+import {useLocationChange} from '../utils/useLocationChange';
+import {useScrollPosition} from '../utils/scrollUtils';
+
+/**
+ * Wires the imperative logic of a hideable navbar.
+ * @param hideOnScroll If `false`, this hook is basically a no-op.
+ */
+export function useHideableNavbar(hideOnScroll: boolean): {
+  /** A ref to the navbar component. Plug this into the actual element. */
+  readonly navbarRef: (node: HTMLElement | null) => void;
+  /** If `false`, the navbar component should not be rendered. */
+  readonly isNavbarVisible: boolean;
+} {
+  const [isNavbarVisible, setIsNavbarVisible] = useState(hideOnScroll);
+  const isFocusedAnchor = useRef(false);
+  const navbarHeight = useRef(0);
+  const navbarRef = useCallback((node: HTMLElement | null) => {
+    if (node !== null) {
+      navbarHeight.current = node.getBoundingClientRect().height;
+    }
+  }, []);
+
+  useScrollPosition(({scrollY: scrollTop}, lastPosition) => {
+    if (!hideOnScroll) {
+      return;
+    }
+
+    // Needed mostly for handling rubber band scrolling.
+    // See https://github.com/facebook/docusaurus/pull/5721
+    if (scrollTop < navbarHeight.current) {
+      setIsNavbarVisible(true);
+      return;
+    }
+
+    if (isFocusedAnchor.current) {
+      isFocusedAnchor.current = false;
+      return;
+    }
+
+    const lastScrollTop = lastPosition?.scrollY;
+    const documentHeight =
+      document.documentElement.scrollHeight - navbarHeight.current;
+    const windowHeight = window.innerHeight;
+
+    if (lastScrollTop && scrollTop >= lastScrollTop) {
+      setIsNavbarVisible(false);
+    } else if (scrollTop + windowHeight < documentHeight) {
+      setIsNavbarVisible(true);
+    }
+  });
+
+  useLocationChange((locationChangeEvent) => {
+    if (!hideOnScroll) {
+      return;
+    }
+
+    // See https://github.com/facebook/docusaurus/pull/8059#issuecomment-1239639480
+    const currentHash = locationChangeEvent.location.hash;
+    const currentHashAnchor = currentHash
+      ? document.getElementById(currentHash.substring(1))
+      : undefined;
+
+    if (currentHashAnchor) {
+      isFocusedAnchor.current = true;
+      setIsNavbarVisible(false);
+      return;
+    }
+
+    setIsNavbarVisible(true);
+  });
+
+  return {navbarRef, isNavbarVisible};
+}

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/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,67 @@
+/**
+ * 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 {useSyncExternalStore} from 'react';
+
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+const windowSizes = {
+  desktop: 'desktop',
+  mobile: 'mobile',
+  ssr: 'ssr',
+} as const;
+
+type WindowSize = keyof typeof windowSizes;
+
+// Note: this value is also hardcoded in Infima
+// Both JS and CSS must have the same value
+// Updating this JS value alone is not enough
+// See https://github.com/facebook/docusaurus/issues/9603
+const DesktopBreakpoint = 996;
+
+function getWindowSize(desktopBreakpoint: number): WindowSize {
+  if (!ExecutionEnvironment.canUseDOM) {
+    throw new Error(
+      'getWindowSize() should only be called after React hydration',
+    );
+  }
+
+  return window.innerWidth > desktopBreakpoint
+    ? windowSizes.desktop
+    : windowSizes.mobile;
+}
+
+function subscribeToWindowResize(onChange: () => void): () => void {
+  window.addEventListener('resize', onChange);
+  return () => {
+    window.removeEventListener('resize', onChange);
+  };
+}
+
+/**
+ * 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.
+ */
+export function useWindowSize({
+  desktopBreakpoint = DesktopBreakpoint,
+}: {
+  desktopBreakpoint?: number;
+} = {}): WindowSize {
+  return useSyncExternalStore(
+    subscribeToWindowResize,
+    () => getWindowSize(desktopBreakpoint),
+    // super important to return a constant value to avoid hydration mismatch
+    // see https://github.com/facebook/docusaurus/issues/9379
+    () => windowSizes.ssr,
+  );
+}