@docusaurus/theme-common 2.0.0-beta.16 → 2.0.0-beta.19

package/src/{utils → hooks}/useTOCHighlight.ts

@@ -6,15 +6,15 @@
  */
 
 import {useEffect, useRef} from 'react';
-import {useThemeConfig} from './useThemeConfig';
+import {useThemeConfig} from '../utils/useThemeConfig';
 
-/*
-TODO make the hardcoded theme-classic classnames configurable
-(or add them to ThemeClassNames?)
- */
+// 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
+/**
+ * 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;
@@ -26,7 +26,7 @@ function getVisibleBoundingClientRect(element: HTMLElement): DOMRect {
 
 /**
  * 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)
+ * 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;
@@ -81,9 +81,9 @@ function getActiveAnchor(
     // 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
-  return anchors[anchors.length - 1];
+  // 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 {
@@ -116,22 +116,31 @@ function useAnchorTopOffsetRef() {
 }
 
 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;
 };
 
-export default function useTOCHighlight(
-  config: TOCHighlightConfig | undefined,
-): void {
+/**
+ * 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
+      // No-op, highlighting is disabled
       return () => {};
     }
 

package/src/hooks/useWindowSize.ts

@@ -12,12 +12,6 @@ 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;
 
@@ -34,14 +28,22 @@ function getWindowSize() {
     : 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 {
+/**
+ * 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';

package/src/index.ts

@@ -5,104 +5,96 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export {useThemeConfig} from './utils/useThemeConfig';
+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 {
   DocSidebarItemsExpandedStateProvider,
   useDocSidebarItemsExpandedState,
-} from './utils/docSidebarItemsExpandedState';
-
-export type {
-  ThemeConfig,
-  UserThemeConfig,
-  Navbar,
-  NavbarItem,
-  NavbarLogo,
-  MultiColumnFooter,
-  SimpleFooter,
-  Footer,
-  FooterLinkItem,
-  ColorModeConfig,
-} from './utils/useThemeConfig';
+} from './contexts/docSidebarItemsExpandedState';
+export {DocsVersionProvider, useDocsVersion} from './contexts/docsVersion';
+export {DocsSidebarProvider, useDocsSidebar} from './contexts/docsSidebar';
 
 export {createStorageSlot, listStorageKeys} from './utils/storageUtils';
 
 export {useAlternatePageUtils} from './utils/useAlternatePageUtils';
 
-export {useContextualSearchFilters} from './utils/useContextualSearchFilters';
-
 export {
   parseCodeBlockTitle,
   parseLanguage,
   parseLines,
+  containsLineNumbers,
+  getPrismCssVariables,
 } from './utils/codeBlockUtils';
 
-export {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './utils/searchUtils';
+export {
+  docVersionSearchTag,
+  DEFAULT_SEARCH_TAG,
+  useContextualSearchFilters,
+} from './utils/searchUtils';
 
 export {
   isDocsPluginEnabled,
-  DocsVersionProvider,
-  useDocsVersion,
   useDocById,
-  DocsSidebarProvider,
-  useDocsSidebar,
   findSidebarCategory,
   findFirstCategoryLink,
   useCurrentSidebarCategory,
   isActiveSidebarItem,
   useSidebarBreadcrumbs,
+  useDocsVersionCandidates,
+  useLayoutDoc,
+  useLayoutDocsSidebar,
+  useDocRouteMetadata,
 } from './utils/docsUtils';
 
-export {isSamePath} from './utils/pathUtils';
-
 export {useTitleFormatter} from './utils/generalUtils';
 
 export {usePluralForm} from './utils/usePluralForm';
 
 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';
+  DocsPreferredVersionContextProvider,
+} from './contexts/docsPreferredVersion';
 
 export {duplicates, uniq} from './utils/jsUtils';
 
-export {DocsPreferredVersionContextProvider} from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
-
 export {ThemeClassNames} from './utils/ThemeClassNames';
 
 export {
   AnnouncementBarProvider,
   useAnnouncementBar,
-} from './utils/announcementBarUtils';
+} from './contexts/announcementBar';
 
 export {useLocalPathname} from './utils/useLocalPathname';
 
-export {translateTagsPageTitle, listTagsByLetters} from './utils/tagsUtils';
-export type {TagLetterEntry} from './utils/tagsUtils';
+export {
+  translateTagsPageTitle,
+  listTagsByLetters,
+  type TagLetterEntry,
+} from './utils/tagsUtils';
 
 export {useHistoryPopHandler} from './utils/historyUtils';
 
-export {default as useTOCHighlight} from './utils/useTOCHighlight';
-export type {TOCHighlightConfig} from './utils/useTOCHighlight';
+export {
+  useTOCHighlight,
+  type TOCHighlightConfig,
+} from './hooks/useTOCHighlight';
 
 export {
   useFilteredAndTreeifiedTOC,
@@ -110,34 +102,62 @@ export {
   type TOCTreeNode,
 } from './utils/tocUtils';
 
+export {isMultiColumnFooterLinks} from './utils/footerUtils';
+
 export {
   ScrollControllerProvider,
   useScrollController,
   useScrollPosition,
   useScrollPositionBlocker,
+  useSmoothScrollTo,
 } from './utils/scrollUtils';
 
 export {
   useIsomorphicLayoutEffect,
   useDynamicCallback,
+  usePrevious,
+  ReactContextError,
 } from './utils/reactUtils';
 
 export {isRegexpStringMatch} from './utils/regexpUtils';
 
-export {useHomePageRoute} from './utils/routesUtils';
+export {useHomePageRoute, isSamePath} from './utils/routesUtils';
+
+export {
+  PageMetadata,
+  HtmlClassNameProvider,
+  PluginHtmlClassNameProvider,
+} from './utils/metadataUtils';
+
+export {
+  useColorMode,
+  ColorModeProvider,
+  type ColorMode,
+} from './contexts/colorMode';
+
+export {splitNavbarItems, NavbarProvider} from './utils/navbarUtils';
 
-export {useColorMode, ColorModeProvider} from './utils/colorModeUtils';
 export {
   useTabGroupChoice,
   TabGroupChoiceProvider,
-} from './utils/tabGroupChoiceUtils';
+} from './contexts/tabGroupChoice';
+
+export {useNavbarMobileSidebar} from './contexts/navbarMobileSidebar';
+export {
+  NavbarSecondaryMenuFiller,
+  type NavbarSecondaryMenuComponent,
+} from './contexts/navbarSecondaryMenu/content';
+export {useNavbarSecondaryMenu} from './contexts/navbarSecondaryMenu/display';
 
-export {default as useHideableNavbar} from './hooks/useHideableNavbar';
+export {useBackToTopButton} from './hooks/useBackToTopButton';
+export {useHideableNavbar} from './hooks/useHideableNavbar';
 export {
-  default as useKeyboardNavigation,
+  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';
+export {usePrismTheme} from './hooks/usePrismTheme';
+export {useLockBodyScroll} from './hooks/useLockBodyScroll';
+export {useWindowSize} from './hooks/useWindowSize';
+export {useSearchPage} from './hooks/useSearchPage';
+export {useCodeWordWrap} from './hooks/useCodeWordWrap';
+export {useSkipToContent} from './hooks/useSkipToContent';

package/src/utils/ThemeClassNames.ts

@@ -5,10 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// 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!
+
+/**
+ * These class names are used to style page layouts in Docusaurus, meant to be
+ * targeted by user-provided custom CSS selectors.
+ */
 export const ThemeClassNames = {
   page: {
     blogListPage: 'blog-list-page',
@@ -17,8 +20,8 @@ export const ThemeClassNames = {
     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
+    docsTagsListPage: 'docs-tags-list-page',
+    docsTagDocListPage: 'docs-tags-doc-list-page',
 
     mdxPage: 'mdx-page',
   },
@@ -29,8 +32,9 @@ export const ThemeClassNames = {
     mdxPages: 'mdx-wrapper',
   },
 
-  // /!\ Please keep the naming convention consistent!
-  // Something like: "theme-{blog,doc,version,page}?-<suffix>"
+  /**
+   * Follows the naming convention "theme-{blog,doc,version,page}?-<suffix>"
+   */
   common: {
     editThisPage: 'theme-edit-this-page',
     lastUpdated: 'theme-last-updated',