@docusaurus/theme-common 2.0.0-beta.15d451942 → 2.0.0-beta.16

package/src/components/Details/index.tsx

@@ -0,0 +1,102 @@
+/**
+ * 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 ComponentProps,
+  type ReactElement,
+  useRef,
+  useState,
+} from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import clsx from 'clsx';
+import {useCollapsible, Collapsible} from '../Collapsible';
+import styles from './styles.module.css';
+
+function isInSummary(node: HTMLElement | null): boolean {
+  if (!node) {
+    return false;
+  }
+  return node.tagName === 'SUMMARY' || isInSummary(node.parentElement);
+}
+
+function hasParent(node: HTMLElement | null, parent: HTMLElement): boolean {
+  if (!node) {
+    return false;
+  }
+  return node === parent || hasParent(node.parentElement, parent);
+}
+
+export type DetailsProps = {
+  summary?: ReactElement;
+} & ComponentProps<'details'>;
+
+export default function Details({
+  summary,
+  children,
+  ...props
+}: DetailsProps): JSX.Element {
+  const isBrowser = useIsBrowser();
+  const detailsRef = useRef<HTMLDetailsElement>(null);
+
+  const {collapsed, setCollapsed} = useCollapsible({
+    initialState: !props.open,
+  });
+  // Use a separate prop because it must be set only after animation completes
+  // Otherwise close anim won't work
+  const [open, setOpen] = useState(props.open);
+
+  return (
+    // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-noninteractive-element-interactions
+    <details
+      {...props}
+      ref={detailsRef}
+      open={open}
+      data-collapsed={collapsed}
+      className={clsx(
+        styles.details,
+        {[styles.isBrowser]: isBrowser},
+        props.className,
+      )}
+      onMouseDown={(e) => {
+        const target = e.target as HTMLElement;
+        // Prevent a double-click to highlight summary text
+        if (isInSummary(target) && e.detail > 1) {
+          e.preventDefault();
+        }
+      }}
+      onClick={(e) => {
+        e.stopPropagation(); // For isolation of multiple nested details/summary
+        const target = e.target as HTMLElement;
+        const shouldToggle =
+          isInSummary(target) && hasParent(target, detailsRef.current!);
+        if (!shouldToggle) {
+          return;
+        }
+        e.preventDefault();
+        if (collapsed) {
+          setCollapsed(false);
+          setOpen(true);
+        } else {
+          setCollapsed(true);
+          // setOpen(false); // Don't do this, it breaks close animation!
+        }
+      }}>
+      {summary}
+
+      <Collapsible
+        lazy={false} // Content might matter for SEO in this case
+        collapsed={collapsed}
+        disableSSRStyle // Allows component to work fine even with JS disabled!
+        onCollapseTransitionEnd={(newCollapsed) => {
+          setCollapsed(newCollapsed);
+          setOpen(!newCollapsed);
+        }}>
+        <div className={styles.collapsibleContent}>{children}</div>
+      </Collapsible>
+    </details>
+  );
+}

package/src/components/Details/styles.module.css

@@ -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.
+ */
+
+/*
+CSS variables, meant to be overridden by final theme
+ */
+.details {
+  --docusaurus-details-summary-arrow-size: 0.38rem;
+  --docusaurus-details-transition: transform 200ms ease;
+  --docusaurus-details-decoration-color: grey;
+}
+
+.details > summary {
+  position: relative;
+  cursor: pointer;
+  list-style: none;
+  padding-left: 1rem;
+}
+
+/* TODO: deprecation, need to remove this after Safari will support `::marker` */
+.details > summary::-webkit-details-marker {
+  display: none;
+}
+
+.details > summary::before {
+  position: absolute;
+  top: 0.45rem;
+  left: 0;
+
+  /* CSS-only Arrow */
+  content: '';
+  border-width: var(--docusaurus-details-summary-arrow-size);
+  border-style: solid;
+  border-color: transparent transparent transparent
+    var(--docusaurus-details-decoration-color);
+
+  /* Arrow rotation anim */
+  transform: rotate(0deg);
+  transition: var(--docusaurus-details-transition);
+  transform-origin: calc(var(--docusaurus-details-summary-arrow-size) / 2) 50%;
+}
+
+/* When JS disabled/failed to load: we use the open property for arrow animation: */
+.details[open]:not(.isBrowser) > summary::before,
+/* When JS works: we use the data-attribute for arrow animation */
+.details[data-collapsed='false'].isBrowser > summary::before {
+  transform: rotate(90deg);
+}
+
+.collapsibleContent {
+  margin-top: 1rem;
+  border-top: 1px solid var(--docusaurus-details-decoration-color);
+  padding-top: 1rem;
+}

package/src/hooks/styles.css

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+body:not(.navigation-with-keyboard) *:not(input):focus {
+  outline: none;
+}

package/src/hooks/useHideableNavbar.ts

@@ -0,0 +1,77 @@
+/**
+ * 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';
+
+type UseHideableNavbarReturns = {
+  readonly navbarRef: (node: HTMLElement | null) => void;
+  readonly isNavbarVisible: boolean;
+};
+
+export default function useHideableNavbar(
+  hideOnScroll: boolean,
+): UseHideableNavbarReturns {
+  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((currentPosition, lastPosition) => {
+    if (!hideOnScroll) {
+      return;
+    }
+
+    const scrollTop = currentPosition.scrollY;
+
+    // It needed for mostly to handle rubber band scrolling
+    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;
+    }
+
+    if (locationChangeEvent.location.hash) {
+      isFocusedAnchor.current = true;
+      setIsNavbarVisible(false);
+      return;
+    }
+
+    setIsNavbarVisible(true);
+  });
+
+  return {
+    navbarRef,
+    isNavbarVisible,
+  };
+}

package/src/hooks/useKeyboardNavigation.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 './styles.css';
+
+export const keyboardFocusedClassName = 'navigation-with-keyboard';
+
+// This hook detect keyboard focus indicator to not show outline for mouse users
+// Inspired by https://hackernoon.com/removing-that-ugly-focus-ring-and-keeping-it-too-6c8727fefcd2
+export default function useKeyboardNavigation(): void {
+  useEffect(() => {
+    function handleOutlineStyles(e: MouseEvent | KeyboardEvent) {
+      if (e.type === 'keydown' && (e as KeyboardEvent).key === 'Tab') {
+        document.body.classList.add(keyboardFocusedClassName);
+      }
+
+      if (e.type === 'mousedown') {
+        document.body.classList.remove(keyboardFocusedClassName);
+      }
+    }
+
+    document.addEventListener('keydown', handleOutlineStyles);
+    document.addEventListener('mousedown', handleOutlineStyles);
+
+    return () => {
+      document.body.classList.remove(keyboardFocusedClassName);
+      document.removeEventListener('keydown', handleOutlineStyles);
+      document.removeEventListener('mousedown', handleOutlineStyles);
+    };
+  }, []);
+}

package/src/hooks/useLockBodyScroll.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 {useEffect} from 'react';
+
+export default function useLockBodyScroll(lock: boolean = true): void {
+  useEffect(() => {
+    document.body.style.overflow = lock ? 'hidden' : 'visible';
+
+    return () => {
+      document.body.style.overflow = 'visible';
+    };
+  }, [lock]);
+}

package/src/hooks/usePrismTheme.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 defaultTheme from 'prism-react-renderer/themes/palenight';
+import {useColorMode} from '../utils/colorModeUtils';
+import {useThemeConfig} from '../utils/useThemeConfig';
+
+export default function usePrismTheme(): typeof defaultTheme {
+  const {prism} = useThemeConfig();
+  const {isDarkTheme} = useColorMode();
+  const lightModeTheme = prism.theme || defaultTheme;
+  const darkModeTheme = prism.darkTheme || lightModeTheme;
+  const prismTheme = isDarkTheme ? darkModeTheme : lightModeTheme;
+
+  return prismTheme;
+}

package/src/hooks/useSearchPage.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 {useHistory} from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useCallback, useEffect, useState} from 'react';
+
+const SEARCH_PARAM_QUERY = 'q';
+
+interface UseSearchPageReturn {
+  searchQuery: string;
+  setSearchQuery: (newSearchQuery: string) => void;
+  generateSearchPageLink: (targetSearchQuery: string) => string;
+}
+
+export default function useSearchPage(): UseSearchPageReturn {
+  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?q=${encodeURIComponent(targetSearchQuery)}`,
+    [baseUrl],
+  );
+
+  return {
+    searchQuery,
+    setSearchQuery,
+    generateSearchPageLink,
+  };
+}

package/src/hooks/useWindowSize.ts

@@ -0,0 +1,70 @@
+/**
+ * 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',
+
+  // This "ssr" value is very important to handle hydration FOUC / layout shifts
+  // You have to handle server-rendering explicitly on the call-site
+  // 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
+  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;
+}
+
+// Simulate the SSR window size in dev, so that potential hydration FOUC/layout
+// shift problems can be seen in dev too!
+const DevSimulateSSR = process.env.NODE_ENV === 'development' && true;
+
+// This hook returns an enum value on purpose!
+// We don't want it to return the actual width value, for resize perf reasons
+// We only want to re-render once a breakpoint is crossed
+export default 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

@@ -6,26 +6,51 @@
  */
 
 export {useThemeConfig} from './utils/useThemeConfig';
+export {
+  DocSidebarItemsExpandedStateProvider,
+  useDocSidebarItemsExpandedState,
+} from './utils/docSidebarItemsExpandedState';
 
 export type {
   ThemeConfig,
+  UserThemeConfig,
   Navbar,
   NavbarItem,
   NavbarLogo,
+  MultiColumnFooter,
+  SimpleFooter,
   Footer,
-  FooterLinks,
   FooterLinkItem,
+  ColorModeConfig,
 } from './utils/useThemeConfig';
 
 export {createStorageSlot, listStorageKeys} from './utils/storageUtils';
 
 export {useAlternatePageUtils} from './utils/useAlternatePageUtils';
 
-export {parseCodeBlockTitle} from './utils/codeBlockUtils';
+export {useContextualSearchFilters} from './utils/useContextualSearchFilters';
+
+export {
+  parseCodeBlockTitle,
+  parseLanguage,
+  parseLines,
+} from './utils/codeBlockUtils';
 
 export {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './utils/searchUtils';
 
-export {isDocsPluginEnabled} from './utils/docsUtils';
+export {
+  isDocsPluginEnabled,
+  DocsVersionProvider,
+  useDocsVersion,
+  useDocById,
+  DocsSidebarProvider,
+  useDocsSidebar,
+  findSidebarCategory,
+  findFirstCategoryLink,
+  useCurrentSidebarCategory,
+  isActiveSidebarItem,
+  useSidebarBreadcrumbs,
+} from './utils/docsUtils';
 
 export {isSamePath} from './utils/pathUtils';
 
@@ -33,13 +58,86 @@ export {useTitleFormatter} from './utils/generalUtils';
 
 export {usePluralForm} from './utils/usePluralForm';
 
-export {useChangeRoute} from './utils/useChangeRoute';
+export {useLocationChange} from './utils/useLocationChange';
+
+export {usePrevious} from './utils/usePrevious';
+
+export {useCollapsible, Collapsible} from './components/Collapsible';
+export type {
+  UseCollapsibleConfig,
+  UseCollapsibleReturns,
+} from './components/Collapsible';
+
+export {default as Details} from './components/Details';
+export type {DetailsProps} from './components/Details';
+
+export {
+  MobileSecondaryMenuProvider,
+  MobileSecondaryMenuFiller,
+  useMobileSecondaryMenuRenderer,
+} from './utils/mobileSecondaryMenu';
+export type {MobileSecondaryMenuComponent} from './utils/mobileSecondaryMenu';
 
 export {
   useDocsPreferredVersion,
   useDocsPreferredVersionByPluginId,
 } from './utils/docsPreferredVersion/useDocsPreferredVersion';
 
+export {duplicates, uniq} from './utils/jsUtils';
+
 export {DocsPreferredVersionContextProvider} from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 
 export {ThemeClassNames} from './utils/ThemeClassNames';
+
+export {
+  AnnouncementBarProvider,
+  useAnnouncementBar,
+} from './utils/announcementBarUtils';
+
+export {useLocalPathname} from './utils/useLocalPathname';
+
+export {translateTagsPageTitle, listTagsByLetters} from './utils/tagsUtils';
+export type {TagLetterEntry} from './utils/tagsUtils';
+
+export {useHistoryPopHandler} from './utils/historyUtils';
+
+export {default as useTOCHighlight} from './utils/useTOCHighlight';
+export type {TOCHighlightConfig} from './utils/useTOCHighlight';
+
+export {
+  useFilteredAndTreeifiedTOC,
+  useTreeifiedTOC,
+  type TOCTreeNode,
+} from './utils/tocUtils';
+
+export {
+  ScrollControllerProvider,
+  useScrollController,
+  useScrollPosition,
+  useScrollPositionBlocker,
+} from './utils/scrollUtils';
+
+export {
+  useIsomorphicLayoutEffect,
+  useDynamicCallback,
+} from './utils/reactUtils';
+
+export {isRegexpStringMatch} from './utils/regexpUtils';
+
+export {useHomePageRoute} from './utils/routesUtils';
+
+export {useColorMode, ColorModeProvider} from './utils/colorModeUtils';
+export {
+  useTabGroupChoice,
+  TabGroupChoiceProvider,
+} from './utils/tabGroupChoiceUtils';
+
+export {default as useHideableNavbar} from './hooks/useHideableNavbar';
+export {
+  default as useKeyboardNavigation,
+  keyboardFocusedClassName,
+} from './hooks/useKeyboardNavigation';
+export {default as usePrismTheme} from './hooks/usePrismTheme';
+export {default as useLockBodyScroll} from './hooks/useLockBodyScroll';
+export {default as useWindowSize} from './hooks/useWindowSize';
+export {default as useSearchPage} from './hooks/useSearchPage';

package/src/types.d.ts

@@ -5,8 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable import/no-duplicates */
-/* eslint-disable spaced-comment */
 /// <reference types="@docusaurus/module-type-aliases" />
 /// <reference types="@docusaurus/plugin-content-blog" />
 /// <reference types="@docusaurus/plugin-content-docs" />

package/src/utils/ThemeClassNames.ts

@@ -6,19 +6,61 @@
  */
 
 // These class names are used to style page layouts in Docusaurus
+// Those are meant to be targeted by user-provided custom CSS selectors
+// Please do not modify the classnames! This is a breaking change, and annoying
+// for users!
 export const ThemeClassNames = {
   page: {
     blogListPage: 'blog-list-page',
     blogPostPage: 'blog-post-page',
     blogTagsListPage: 'blog-tags-list-page',
-    blogTagsPostPage: 'blog-tags-post-page',
-    docPage: 'doc-page',
+    blogTagPostListPage: 'blog-tags-post-list-page',
+
+    docsDocPage: 'docs-doc-page',
+    docsTagsListPage: 'docs-tags-list-page', // List of tags
+    docsTagDocListPage: 'docs-tags-doc-list-page', // Docs for a tag
+
     mdxPage: 'mdx-page',
   },
   wrapper: {
     main: 'main-wrapper',
     blogPages: 'blog-wrapper',
-    docPages: 'docs-wrapper',
+    docsPages: 'docs-wrapper',
     mdxPages: 'mdx-wrapper',
   },
-};
+
+  // /!\ Please keep the naming convention consistent!
+  // Something like: "theme-{blog,doc,version,page}?-<suffix>"
+  common: {
+    editThisPage: 'theme-edit-this-page',
+    lastUpdated: 'theme-last-updated',
+    backToTopButton: 'theme-back-to-top-button',
+    codeBlock: 'theme-code-block',
+  },
+  layout: {
+    // TODO add other stable classNames here
+  },
+  docs: {
+    docVersionBanner: 'theme-doc-version-banner',
+    docVersionBadge: 'theme-doc-version-badge',
+    docBreadcrumbs: 'theme-doc-breadcrumbs',
+    docMarkdown: 'theme-doc-markdown',
+    docTocMobile: 'theme-doc-toc-mobile',
+    docTocDesktop: 'theme-doc-toc-desktop',
+    docFooter: 'theme-doc-footer',
+    docFooterTagsRow: 'theme-doc-footer-tags-row',
+    docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
+    docSidebarContainer: 'theme-doc-sidebar-container',
+    docSidebarMenu: 'theme-doc-sidebar-menu',
+    docSidebarItemCategory: 'theme-doc-sidebar-item-category',
+    docSidebarItemLink: 'theme-doc-sidebar-item-link',
+    docSidebarItemCategoryLevel: (level: number) =>
+      `theme-doc-sidebar-item-category-level-${level}` as const,
+    docSidebarItemLinkLevel: (level: number) =>
+      `theme-doc-sidebar-item-link-level-${level}` as const,
+    // TODO add other stable classNames here
+  },
+  blog: {
+    // TODO add other stable classNames here
+  },
+} as const;