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

package/src/utils/scrollUtils.tsx

@@ -0,0 +1,303 @@
+/**
+ * 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, {
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {useEvent, ReactContextError} from './reactUtils';
+
+type ScrollController = {
+  /** A boolean ref tracking whether scroll events are enabled. */
+  scrollEventsEnabledRef: React.RefObject<boolean>;
+  /** Enable scroll events in `useScrollPosition`. */
+  enableScrollEvents: () => void;
+  /** Disable 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 = React.createContext<ScrollController | undefined>(
+  undefined,
+);
+
+export function ScrollControllerProvider({
+  children,
+}: {
+  children: ReactNode;
+}): ReactNode {
+  const value = useScrollControllerContextValue();
+  return <ScrollMonitorContext value={value}>{children}</ScrollMonitorContext>;
+}
+
+/**
+ * We need a way to update the scroll position while ignoring scroll events
+ * so as not to toggle Navbar/BackToTop visibility.
+ *
+ * This API permits to temporarily disable/ignore scroll events. Motivated by
+ * https://github.com/facebook/docusaurus/pull/5618
+ */
+export function useScrollController(): ScrollController {
+  const context = useContext(ScrollMonitorContext);
+  if (context == null) {
+    throw new ReactContextError('ScrollControllerProvider');
+  }
+  return context;
+}
+
+type ScrollPosition = {scrollX: number; scrollY: number};
+
+const getScrollPosition = (): ScrollPosition | null =>
+  ExecutionEnvironment.canUseDOM
+    ? {
+        scrollX: window.pageXOffset,
+        scrollY: window.pageYOffset,
+      }
+    : null;
+
+/**
+ * This hook fires an effect when the scroll position changes. The effect will
+ * be provided with the before/after scroll positions. Note that the effect may
+ * not be always run: if scrolling is disabled through `useScrollController`, it
+ * will be a no-op.
+ *
+ * @see {@link useScrollController}
+ */
+export function useScrollPosition(
+  effect: (
+    position: ScrollPosition,
+    lastPosition: ScrollPosition | null,
+  ) => void,
+  deps: unknown[] = [],
+): void {
+  const {scrollEventsEnabledRef} = useScrollController();
+  const lastPositionRef = useRef<ScrollPosition | null>(getScrollPosition());
+
+  const dynamicEffect = useEvent(effect);
+
+  useEffect(() => {
+    const handleScroll = () => {
+      if (!scrollEventsEnabledRef.current) {
+        return;
+      }
+      const currentPosition = getScrollPosition()!;
+      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);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [dynamicEffect, scrollEventsEnabledRef, ...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]);
+}
+
+/**
+ * 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 https://github.com/facebook/docusaurus/pull/5618
+ */
+export function useScrollPositionBlocker(): {
+  /**
+   * Takes an element, and keeps its screen position no matter what's getting
+   * rendered above it, until the next render.
+   */
+  blockElementScrollPositionUntilNextRender: (el: HTMLElement) => void;
+} {
+  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 the
+        // scrollController events again.
+        if (restored) {
+          const handleScrollRestoreEvent = () => {
+            scrollController.enableScrollEvents();
+            window.removeEventListener('scroll', handleScrollRestoreEvent);
+          };
+          window.addEventListener('scroll', handleScrollRestoreEvent);
+        } else {
+          scrollController.enableScrollEvents();
+        }
+      };
+    },
+    [scrollController, scrollPositionSaver],
+  );
+
+  useLayoutEffect(() => {
+    // Queuing permits to restore scroll position after all useLayoutEffect
+    // have run, and yet preserve the sync nature of the scroll restoration
+    // See https://github.com/facebook/docusaurus/issues/8625
+    queueMicrotask(() => nextLayoutEffectCallbackRef.current?.());
+  });
+
+  return {
+    blockElementScrollPositionUntilNextRender,
+  };
+}
+
+type CancelScrollTop = () => void;
+
+function smoothScrollNative(top: number): CancelScrollTop {
+  window.scrollTo({top, behavior: 'smooth'});
+  return () => {
+    // Nothing to cancel, it's natively cancelled if user tries to scroll down
+  };
+}
+
+function smoothScrollPolyfill(top: number): CancelScrollTop {
+  let raf: number | null = null;
+  const isUpScroll = document.documentElement.scrollTop > top;
+  function rafRecursion() {
+    const currentScroll = document.documentElement.scrollTop;
+    if (
+      (isUpScroll && currentScroll > top) ||
+      (!isUpScroll && currentScroll < top)
+    ) {
+      raf = requestAnimationFrame(rafRecursion);
+      window.scrollTo(0, Math.floor((currentScroll - top) * 0.85) + top);
+    }
+  }
+  rafRecursion();
+
+  // Break the recursion. Prevents the user from "fighting" against that
+  // recursion producing a weird UX
+  return () => raf && cancelAnimationFrame(raf);
+}
+
+/**
+ * A "smart polyfill" of `window.scrollTo({ top, behavior: "smooth" })`.
+ * This currently always uses a polyfilled implementation unless
+ * `scroll-behavior: smooth` has been set in CSS, because native support
+ * detection for scroll behavior seems unreliable.
+ *
+ * This hook does not do anything by itself: it returns a start and a stop
+ * handle. You can execute either handle at any time.
+ */
+export function useSmoothScrollTo(): {
+  /**
+   * Start the scroll.
+   *
+   * @param top The final scroll top position.
+   */
+  startScroll: (top: number) => void;
+  /**
+   * A cancel function, because the non-native smooth scroll-top
+   * implementation must be interrupted if user scrolls down. If there's no
+   * existing animation or the scroll is using native behavior, this is a no-op.
+   */
+  cancelScroll: CancelScrollTop;
+} {
+  const cancelRef = useRef<CancelScrollTop | null>(null);
+  const isBrowser = useIsBrowser();
+  // Not all have support for smooth scrolling (particularly Safari mobile iOS)
+  // TODO proper detection is currently unreliable!
+  // see https://github.com/wessberg/scroll-behavior-polyfill/issues/16
+  // For now, we only use native scroll behavior if smooth is already set,
+  // because otherwise the polyfill produces a weird UX when both CSS and JS try
+  // to scroll a page, and they cancel each other.
+  const supportsNativeSmoothScrolling =
+    isBrowser &&
+    getComputedStyle(document.documentElement).scrollBehavior === 'smooth';
+  return {
+    startScroll: (top: number) => {
+      cancelRef.current = supportsNativeSmoothScrolling
+        ? smoothScrollNative(top)
+        : smoothScrollPolyfill(top);
+    },
+    cancelScroll: () => cancelRef.current?.(),
+  };
+}

package/src/utils/searchUtils.ts

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export const DEFAULT_SEARCH_TAG = 'default';

package/src/utils/skipToContentUtils.tsx

@@ -0,0 +1,108 @@
+/**
+ * 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, type ComponentProps, type ReactNode} from 'react';
+import {useHistory} from '@docusaurus/router';
+import {translate} from '@docusaurus/Translate';
+import {useLocationChange} from './useLocationChange';
+
+/**
+ * The id of the element that should become focused on a page
+ * that does not have a <main> html tag.
+ * Focusing the Docusaurus Layout children is a reasonable fallback.
+ *
+ * __ prefix allows search crawlers (Algolia/DocSearch) to ignore anchors
+ * https://github.com/facebook/docusaurus/issues/8883#issuecomment-1516328368
+ */
+export const SkipToContentFallbackId = '__docusaurus_skipToContent_fallback';
+
+/**
+ * Returns the skip to content element to focus when the link is clicked.
+ */
+function getSkipToContentTarget(): HTMLElement | null {
+  return (
+    // Try to focus the <main> in priority
+    // Note: this will only work if JS is enabled
+    // See https://github.com/facebook/docusaurus/issues/6411#issuecomment-1284136069
+    document.querySelector('main:first-of-type') ??
+    // Then try to focus the fallback element (usually the Layout children)
+    document.getElementById(SkipToContentFallbackId)
+  );
+}
+
+function programmaticFocus(el: HTMLElement) {
+  el.setAttribute('tabindex', '-1');
+  el.focus();
+  el.removeAttribute('tabindex');
+}
+
+/** This hook wires the logic for a skip-to-content link. */
+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.
+   */
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  /**
+   * Callback fired when the skip to content link has been clicked.
+   * It will programmatically focus the main content.
+   */
+  onClick: (e: React.MouseEvent<HTMLAnchorElement>) => void;
+} {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const {action} = useHistory();
+
+  const onClick = useCallback((e: React.MouseEvent<HTMLAnchorElement>) => {
+    e.preventDefault();
+    const targetElement = getSkipToContentTarget();
+    if (targetElement) {
+      programmaticFocus(targetElement);
+    }
+  }, []);
+
+  // "Reset" focus when navigating.
+  // See https://github.com/facebook/docusaurus/pull/8204#issuecomment-1276547558
+  useLocationChange(({location}) => {
+    if (containerRef.current && !location.hash && action === 'PUSH') {
+      programmaticFocus(containerRef.current);
+    }
+  });
+
+  return {containerRef, onClick};
+}
+
+const DefaultSkipToContentLabel = translate({
+  id: 'theme.common.skipToMainContent',
+  description:
+    'The skip to content label used for accessibility, allowing to rapidly navigate to main content with keyboard tab/enter navigation',
+  message: 'Skip to main content',
+});
+
+type SkipToContentLinkProps = Omit<ComponentProps<'a'>, 'href' | 'onClick'>;
+
+export function SkipToContentLink(props: SkipToContentLinkProps): ReactNode {
+  const linkLabel = props.children ?? DefaultSkipToContentLabel;
+  const {containerRef, onClick} = useSkipToContent();
+  return (
+    <div
+      ref={containerRef}
+      role="region"
+      aria-label={DefaultSkipToContentLabel}>
+      {/* eslint-disable-next-line @docusaurus/no-html-links */}
+      <a
+        {...props}
+        // Note this is a fallback href in case JS is disabled
+        // It has limitations, see https://github.com/facebook/docusaurus/issues/6411#issuecomment-1284136069
+        href={`#${SkipToContentFallbackId}`}
+        onClick={onClick}>
+        {linkLabel}
+      </a>
+    </div>
+  );
+}

package/src/utils/storageUtils.ts

@@ -0,0 +1,260 @@
+/**
+ * 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, useState, useSyncExternalStore} from 'react';
+import SiteStorage from '@generated/site-storage';
+
+export type StorageType = (typeof SiteStorage)['type'] | 'none';
+
+const DefaultStorageType: StorageType = SiteStorage.type;
+
+function applyNamespace(storageKey: string): string {
+  return `${storageKey}${SiteStorage.namespace}`;
+}
+
+// window.addEventListener('storage') only works for different windows...
+// so for current window we have to dispatch the event manually
+// Now we can listen for both cross-window / current-window storage changes!
+// see https://stackoverflow.com/a/71177640/82609
+// see https://stackoverflow.com/questions/26974084/listen-for-changes-with-localstorage-on-the-same-window
+function dispatchChangeEvent({
+  key,
+  oldValue,
+  newValue,
+  storage,
+}: {
+  key: string;
+  oldValue: string | null;
+  newValue: string | null;
+  storage: Storage;
+}) {
+  // If we set multiple times the same storage value, events should not be fired
+  // The native events behave this way, so our manual event dispatch should
+  // rather behave exactly the same. Not doing so might create infinite loops.
+  // See https://github.com/facebook/docusaurus/issues/8594
+  if (oldValue === newValue) {
+    return;
+  }
+  const event = document.createEvent('StorageEvent');
+  event.initStorageEvent(
+    'storage',
+    false,
+    false,
+    key,
+    oldValue,
+    newValue,
+    window.location.href,
+    storage,
+  );
+  window.dispatchEvent(event);
+}
+
+/**
+ * Will return `null` if browser storage is unavailable (like running Docusaurus
+ * in an iframe). This should NOT be called in SSR.
+ *
+ * @see https://github.com/facebook/docusaurus/pull/4501
+ */
+function getBrowserStorage(
+  storageType: StorageType = DefaultStorageType,
+): Storage | null {
+  if (typeof window === 'undefined') {
+    throw new Error(
+      'Browser storage is not available on Node.js/Docusaurus SSR process.',
+    );
+  }
+  if (storageType === 'none') {
+    return null;
+  }
+  try {
+    return window[storageType];
+  } catch (err) {
+    logOnceBrowserStorageNotAvailableWarning(err as Error);
+    return null;
+  }
+}
+
+let hasLoggedBrowserStorageNotAvailableWarning = false;
+/**
+ * Poor man's memoization to avoid logging multiple times the same warning.
+ * Sometimes, `localStorage`/`sessionStorage` is unavailable due to browser
+ * policies.
+ */
+function logOnceBrowserStorageNotAvailableWarning(error: Error) {
+  if (!hasLoggedBrowserStorageNotAvailableWarning) {
+    console.warn(
+      `Docusaurus browser storage is not available.
+Possible reasons: running Docusaurus in an iframe, in an incognito browser session, or using too strict browser privacy settings.`,
+      error,
+    );
+    hasLoggedBrowserStorageNotAvailableWarning = true;
+  }
+}
+
+// Convenient storage interface for a single storage key
+export type StorageSlot = {
+  get: () => string | null;
+  set: (value: string) => void;
+  del: () => void;
+  listen: (onChange: (event: StorageEvent) => void) => () => void;
+};
+
+const NoopStorageSlot: StorageSlot = {
+  get: () => null,
+  set: () => {},
+  del: () => {},
+  listen: () => () => {},
+};
+
+// Fail-fast, as storage APIs should not be used during the SSR process
+function createServerStorageSlot(key: string): StorageSlot {
+  function throwError(): never {
+    throw new Error(`Illegal storage API usage for storage key "${key}".
+Docusaurus storage APIs are not supposed to be called on the server-rendering process.
+Please only call storage APIs in effects and event handlers.`);
+  }
+
+  return {
+    get: throwError,
+    set: throwError,
+    del: throwError,
+    listen: throwError,
+  };
+}
+
+/**
+ * Creates an interface to work on a particular key in the storage model.
+ * Note that this function only initializes the interface, but doesn't allocate
+ * anything by itself (i.e. no side-effects).
+ *
+ * The API is fail-safe, since usage of browser storage should be considered
+ * unreliable. Local storage might simply be unavailable (iframe + browser
+ * security) or operations might fail individually. Please assume that using
+ * this API can be a no-op. See also https://github.com/facebook/docusaurus/issues/6036
+ */
+export function createStorageSlot(
+  keyInput: string,
+  options?: {persistence?: StorageType},
+): StorageSlot {
+  const key = applyNamespace(keyInput);
+  if (typeof window === 'undefined') {
+    return createServerStorageSlot(key);
+  }
+  const storage = getBrowserStorage(options?.persistence);
+  if (storage === null) {
+    return NoopStorageSlot;
+  }
+  return {
+    get: () => {
+      try {
+        return storage.getItem(key);
+      } catch (err) {
+        console.error(`Docusaurus storage error, can't get key=${key}`, err);
+        return null;
+      }
+    },
+    set: (newValue) => {
+      try {
+        const oldValue = storage.getItem(key);
+        storage.setItem(key, newValue);
+        dispatchChangeEvent({
+          key,
+          oldValue,
+          newValue,
+          storage,
+        });
+      } catch (err) {
+        console.error(
+          `Docusaurus storage error, can't set ${key}=${newValue}`,
+          err,
+        );
+      }
+    },
+    del: () => {
+      try {
+        const oldValue = storage.getItem(key);
+        storage.removeItem(key);
+        dispatchChangeEvent({key, oldValue, newValue: null, storage});
+      } catch (err) {
+        console.error(`Docusaurus storage error, can't delete key=${key}`, err);
+      }
+    },
+    listen: (onChange) => {
+      try {
+        const listener = (event: StorageEvent) => {
+          if (event.storageArea === storage && event.key === key) {
+            onChange(event);
+          }
+        };
+        window.addEventListener('storage', listener);
+        return () => window.removeEventListener('storage', listener);
+      } catch (err) {
+        console.error(
+          `Docusaurus storage error, can't listen for changes of key=${key}`,
+          err,
+        );
+        return () => {};
+      }
+    },
+  };
+}
+
+export function useStorageSlot(
+  key: string | null,
+  options?: {persistence?: StorageType},
+): [string | null, StorageSlot] {
+  // Not ideal but good enough: assumes storage slot config is constant
+  const [storageSlot] = useState(() => {
+    if (key === null) {
+      return NoopStorageSlot;
+    }
+    return createStorageSlot(key, options);
+  });
+
+  const listen: StorageSlot['listen'] = useCallback(
+    (onChange) => {
+      // Do not try to add a listener during SSR
+      if (typeof window === 'undefined') {
+        return () => {};
+      }
+      return storageSlot.listen(onChange);
+    },
+    [storageSlot],
+  );
+
+  const currentValue = useSyncExternalStore(
+    listen,
+    () => {
+      return storageSlot.get();
+    },
+    () => null,
+  );
+
+  return [currentValue, storageSlot];
+}
+
+/**
+ * Returns a list of all the keys currently stored in browser storage,
+ * or an empty list if browser storage can't be accessed.
+ */
+export function listStorageKeys(
+  storageType: StorageType = DefaultStorageType,
+): string[] {
+  const browserStorage = getBrowserStorage(storageType);
+  if (!browserStorage) {
+    return [];
+  }
+
+  const keys: string[] = [];
+  for (let i = 0; i < browserStorage.length; i += 1) {
+    const key = browserStorage.key(i);
+    if (key !== null) {
+      keys.push(key);
+    }
+  }
+  return keys;
+}