@docusaurus/theme-common 2.0.0-beta.21 → 2.0.0-beta.22

package/src/contexts/blogPost.tsx

@@ -0,0 +1,80 @@
+/**
+ * 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, {useMemo, type ReactNode, useContext} from 'react';
+import {ReactContextError} from '../utils/reactUtils';
+
+import type {PropBlogPostContent} from '@docusaurus/plugin-content-blog';
+
+/**
+ * The React context value returned by the `useBlogPost()` hook.
+ * It contains useful data related to the currently browsed blog post.
+ */
+export type BlogPostContextValue = Pick<
+  PropBlogPostContent,
+  'metadata' | 'frontMatter' | 'assets' | 'toc'
+> & {
+  readonly isBlogPostPage: boolean;
+};
+
+const Context = React.createContext<BlogPostContextValue | null>(null);
+
+/**
+ * Note: we don't use `PropBlogPostContent` as context value on purpose. Metadata is
+ * currently stored inside the MDX component, but we may want to change that in
+ * the future.
+ */
+function useContextValue({
+  content,
+  isBlogPostPage,
+}: {
+  content: PropBlogPostContent;
+  isBlogPostPage: boolean;
+}): BlogPostContextValue {
+  return useMemo(
+    () => ({
+      metadata: content.metadata,
+      frontMatter: content.frontMatter,
+      assets: content.assets,
+      toc: content.toc,
+      isBlogPostPage,
+    }),
+    [content, isBlogPostPage],
+  );
+}
+
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the blog post to the children tree.
+ */
+export function BlogPostProvider({
+  children,
+  content,
+  isBlogPostPage = false,
+}: {
+  children: ReactNode;
+  content: PropBlogPostContent;
+  isBlogPostPage?: boolean;
+}): JSX.Element {
+  const contextValue = useContextValue({content, isBlogPostPage});
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+/**
+ * Returns the data of the currently browsed blog post. Gives access to
+ * front matter, metadata, TOC, etc.
+ * When swizzling a low-level component (e.g. the "Edit this page" link)
+ * and you need some extra metadata, you don't have to drill the props
+ * all the way through the component tree: simply use this hook instead.
+ */
+export function useBlogPost(): BlogPostContextValue {
+  const blogPost = useContext(Context);
+  if (blogPost === null) {
+    throw new ReactContextError('BlogPostProvider');
+  }
+  return blogPost;
+}

package/src/contexts/doc.tsx

@@ -0,0 +1,71 @@
+/**
+ * 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, {useMemo, type ReactNode, useContext} from 'react';
+import {ReactContextError} from '../utils/reactUtils';
+import type {PropDocContent} from '@docusaurus/plugin-content-docs';
+
+/**
+ * The React context value returned by the `useDoc()` hook.
+ * It contains useful data related to the currently browsed doc.
+ */
+export type DocContextValue = Pick<
+  PropDocContent,
+  'metadata' | 'frontMatter' | 'toc' | 'assets' | 'contentTitle'
+>;
+
+const Context = React.createContext<DocContextValue | null>(null);
+
+/**
+ * Note: we don't use `PropDoc` as context value on purpose. Metadata is
+ * currently stored inside the MDX component, but we may want to change that in
+ * the future. This layer is a good opportunity to decouple storage from
+ * consuming API, potentially allowing us to provide metadata as both props and
+ * route context without duplicating the chunks in the future.
+ */
+function useContextValue(content: PropDocContent): DocContextValue {
+  return useMemo(
+    () => ({
+      metadata: content.metadata,
+      frontMatter: content.frontMatter,
+      assets: content.assets,
+      contentTitle: content.contentTitle,
+      toc: content.toc,
+    }),
+    [content],
+  );
+}
+
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the doc to the children tree.
+ */
+export function DocProvider({
+  children,
+  content,
+}: {
+  children: ReactNode;
+  content: PropDocContent;
+}): JSX.Element {
+  const contextValue = useContextValue(content);
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+/**
+ * Returns the data of the currently browsed doc. Gives access to the doc's MDX
+ * Component, front matter, metadata, TOC, etc. When swizzling a low-level
+ * component (e.g. the "Edit this page" link) and you need some extra metadata,
+ * you don't have to drill the props all the way through the component tree:
+ * simply use this hook instead.
+ */
+export function useDoc(): DocContextValue {
+  const doc = useContext(Context);
+  if (doc === null) {
+    throw new ReactContextError('DocProvider');
+  }
+  return doc;
+}

package/src/contexts/docsPreferredVersion.tsx

@@ -175,7 +175,7 @@ function DocsPreferredVersionContextProviderUnsafe({
 export function DocsPreferredVersionContextProvider({
   children,
 }: {
-  children: JSX.Element;
+  children: ReactNode;
 }): JSX.Element {
   if (isDocsPluginEnabled) {
     return (
@@ -184,7 +184,7 @@ export function DocsPreferredVersionContextProvider({
       </DocsPreferredVersionContextProviderUnsafe>
     );
   }
-  return children;
+  return <>{children}</>;
 }
 
 function useDocsPreferredVersionContext(): ContextValue {

package/src/contexts/navbarSecondaryMenu/content.tsx

@@ -9,11 +9,10 @@ import React, {
   useState,
   useContext,
   useEffect,
-  useMemo,
   type ReactNode,
   type ComponentType,
 } from 'react';
-import {ReactContextError} from '../../utils/reactUtils';
+import {ReactContextError, useShallowMemoObject} from '../../utils/reactUtils';
 
 // This context represents a "global layout store". A component (usually a
 // layout component) can request filling this store through
@@ -61,15 +60,6 @@ export function useNavbarSecondaryMenuContent(): Content {
   return value[0];
 }
 
-function useShallowMemoizedObject<O>(obj: O) {
-  return useMemo(
-    () => obj,
-    // Is this safe?
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [...Object.keys(obj), ...Object.values(obj)],
-  );
-}
-
 /**
  * This component renders nothing by itself, but it fills the placeholder in the
  * generic secondary menu layout. This reduces coupling between the main layout
@@ -94,7 +84,7 @@ export function NavbarSecondaryMenuFiller<P extends object>({
   const [, setContent] = context;
 
   // To avoid useless context re-renders, props are memoized shallowly
-  const memoizedProps = useShallowMemoizedObject(props);
+  const memoizedProps = useShallowMemoObject(props);
 
   useEffect(() => {
     // @ts-expect-error: this context is hard to type

package/src/hooks/useCodeWordWrap.ts

@@ -4,9 +4,53 @@
  * 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>,
+  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 function useCodeWordWrap(): {
   readonly codeBlockRef: RefObject<HTMLPreElement>;
@@ -25,6 +69,9 @@ export function useCodeWordWrap(): {
       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);
@@ -38,6 +85,8 @@ export function useCodeWordWrap(): {
     setIsCodeScrollable(isScrollable);
   }, [codeBlockRef]);
 
+  useTabBecameVisibleCallback(codeBlockRef, updateCodeIsScrollable);
+
   useEffect(() => {
     updateCodeIsScrollable();
   }, [isEnabled, updateCodeIsScrollable]);

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/index.ts

@@ -5,6 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/*
+ * APIs to document
+ */
+
 export {
   useThemeConfig,
   type ThemeConfig,
@@ -19,69 +23,42 @@ export {
   type FooterLinkItem,
   type ColorModeConfig,
 } from './utils/useThemeConfig';
-export {
-  DocSidebarItemsExpandedStateProvider,
-  useDocSidebarItemsExpandedState,
-} 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/searchUtils';
 
-export {
-  parseCodeBlockTitle,
-  parseLanguage,
-  parseLines,
-  containsLineNumbers,
-  getPrismCssVariables,
-} from './utils/codeBlockUtils';
-
-export {
-  docVersionSearchTag,
-  DEFAULT_SEARCH_TAG,
-  useContextualSearchFilters,
-} from './utils/searchUtils';
-
-export {
-  isDocsPluginEnabled,
-  useDocById,
-  findSidebarCategory,
-  findFirstCategoryLink,
-  useCurrentSidebarCategory,
-  isActiveSidebarItem,
-  useSidebarBreadcrumbs,
-  useDocsVersionCandidates,
-  useLayoutDoc,
-  useLayoutDocsSidebar,
-  useDocRouteMetadata,
-} from './utils/docsUtils';
-
-export {useTitleFormatter} from './utils/generalUtils';
+export {useCurrentSidebarCategory} from './utils/docsUtils';
 
 export {usePluralForm} from './utils/usePluralForm';
 
-export {useLocationChange} from './utils/useLocationChange';
-
 export {useCollapsible, Collapsible} from './components/Collapsible';
 
+export {ThemeClassNames} from './utils/ThemeClassNames';
+
 export {
-  useDocsPreferredVersion,
-  useDocsPreferredVersionByPluginId,
-  DocsPreferredVersionContextProvider,
-} from './contexts/docsPreferredVersion';
+  useIsomorphicLayoutEffect,
+  useEvent,
+  usePrevious,
+  composeProviders,
+  ReactContextError,
+} from './utils/reactUtils';
 
-export {duplicates, uniq} from './utils/jsUtils';
+export {PageMetadata, HtmlClassNameProvider} from './utils/metadataUtils';
 
-export {ThemeClassNames} from './utils/ThemeClassNames';
+export {useColorMode, type ColorMode} from './contexts/colorMode';
 
 export {
-  AnnouncementBarProvider,
-  useAnnouncementBar,
-} from './contexts/announcementBar';
+  NavbarSecondaryMenuFiller,
+  type NavbarSecondaryMenuComponent,
+} from './contexts/navbarSecondaryMenu/content';
 
-export {useLocalPathname} from './utils/useLocalPathname';
+export {useWindowSize} from './hooks/useWindowSize';
+
+/*
+ * APIs kept undocumented, on purpose
+ * Note: we still guarantee retro-compatibility on those
+ */
 
 export {
   translateTagsPageTitle,
@@ -89,75 +66,12 @@ export {
   type TagLetterEntry,
 } from './utils/tagsUtils';
 
-export {useHistoryPopHandler} from './utils/historyUtils';
-
-export {
-  useTOCHighlight,
-  type TOCHighlightConfig,
-} from './hooks/useTOCHighlight';
-
-export {
-  useFilteredAndTreeifiedTOC,
-  useTreeifiedTOC,
-  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, 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 {
-  useTabGroupChoice,
-  TabGroupChoiceProvider,
-} from './contexts/tabGroupChoice';
-
-export {useNavbarMobileSidebar} from './contexts/navbarMobileSidebar';
-export {
-  NavbarSecondaryMenuFiller,
-  type NavbarSecondaryMenuComponent,
-} from './contexts/navbarSecondaryMenu/content';
-export {useNavbarSecondaryMenu} from './contexts/navbarSecondaryMenu/display';
+export {duplicates, uniq} from './utils/jsUtils';
 
-export {useBackToTopButton} from './hooks/useBackToTopButton';
-export {useHideableNavbar} from './hooks/useHideableNavbar';
-export {
-  useKeyboardNavigation,
-  keyboardFocusedClassName,
-} from './hooks/useKeyboardNavigation';
 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';
+
+export {useDocsPreferredVersion} from './contexts/docsPreferredVersion';

package/src/internal.ts

@@ -0,0 +1,122 @@
+/**
+ * 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.
+ */
+
+// This re-export permits to handle some level of retro-compatibility. Users
+// might swizzle unsafe components and expose these internal imports. When we
+// move an API from internal to public, former internal imports should keep
+// working, so that the change doesn't become breaking.
+//
+// Important: this line is removed from build output with the
+// "removeThemeInternalReexport" script for CI checks. This ensures that none of
+// our internal code relies on this re-export and that we don't forget to
+// migrate theme internal imports to public imports.
+//
+// eslint-disable-next-line no-restricted-syntax
+export * from './index';
+
+export {
+  DocSidebarItemsExpandedStateProvider,
+  useDocSidebarItemsExpandedState,
+} from './contexts/docSidebarItemsExpandedState';
+export {DocsVersionProvider, useDocsVersion} from './contexts/docsVersion';
+export {DocsSidebarProvider, useDocsSidebar} from './contexts/docsSidebar';
+
+export {DocProvider, useDoc, type DocContextValue} from './contexts/doc';
+export {
+  BlogPostProvider,
+  useBlogPost,
+  type BlogPostContextValue,
+} from './contexts/blogPost';
+
+export {
+  useDocsPreferredVersionByPluginId,
+  DocsPreferredVersionContextProvider,
+} from './contexts/docsPreferredVersion';
+
+export {
+  AnnouncementBarProvider,
+  useAnnouncementBar,
+} from './contexts/announcementBar';
+
+export {
+  useTabGroupChoice,
+  TabGroupChoiceProvider,
+} from './contexts/tabGroupChoice';
+
+export {useNavbarMobileSidebar} from './contexts/navbarMobileSidebar';
+export {useNavbarSecondaryMenu} from './contexts/navbarSecondaryMenu/display';
+
+export {ColorModeProvider} from './contexts/colorMode';
+
+export {useAlternatePageUtils} from './utils/useAlternatePageUtils';
+
+export {
+  parseCodeBlockTitle,
+  parseLanguage,
+  parseLines,
+  containsLineNumbers,
+} from './utils/codeBlockUtils';
+
+export {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './utils/searchUtils';
+
+export {
+  isDocsPluginEnabled,
+  useDocById,
+  findSidebarCategory,
+  findFirstCategoryLink,
+  isActiveSidebarItem,
+  useSidebarBreadcrumbs,
+  useDocsVersionCandidates,
+  useLayoutDoc,
+  useLayoutDocsSidebar,
+  useDocRouteMetadata,
+} from './utils/docsUtils';
+
+export {useTitleFormatter} from './utils/generalUtils';
+
+export {useLocationChange} from './utils/useLocationChange';
+
+export {useLocalPathname} from './utils/useLocalPathname';
+
+export {useHistoryPopHandler} from './utils/historyUtils';
+
+export {
+  useFilteredAndTreeifiedTOC,
+  useTreeifiedTOC,
+  type TOCTreeNode,
+} from './utils/tocUtils';
+
+export {
+  ScrollControllerProvider,
+  useScrollController,
+  useScrollPosition,
+  useScrollPositionBlocker,
+  useSmoothScrollTo,
+} from './utils/scrollUtils';
+
+export {useHomePageRoute, isSamePath} from './utils/routesUtils';
+
+export {PluginHtmlClassNameProvider} from './utils/metadataUtils';
+
+export {splitNavbarItems, NavbarProvider} from './utils/navbarUtils';
+
+export {
+  useTOCHighlight,
+  type TOCHighlightConfig,
+} from './hooks/useTOCHighlight';
+
+export {useHideableNavbar} from './hooks/useHideableNavbar';
+export {
+  useKeyboardNavigation,
+  keyboardFocusedClassName,
+} from './hooks/useKeyboardNavigation';
+export {useLockBodyScroll} from './hooks/useLockBodyScroll';
+export {useSearchPage} from './hooks/useSearchPage';
+export {useCodeWordWrap} from './hooks/useCodeWordWrap';
+export {useSkipToContent} from './hooks/useSkipToContent';
+export {getPrismCssVariables} from './utils/codeBlockUtils';
+export {useBackToTopButton} from './hooks/useBackToTopButton';

package/src/utils/ThemeClassNames.ts

@@ -31,19 +31,22 @@ export const ThemeClassNames = {
     docsPages: 'docs-wrapper',
     mdxPages: 'mdx-wrapper',
   },
-
-  /**
-   * Follows the naming convention "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',
+    admonition: 'theme-admonition',
+    admonitionType: (type: 'note' | 'tip' | 'danger' | 'info' | 'caution') =>
+      `theme-admonition-${type}`,
   },
   layout: {
     // TODO add other stable classNames here
   },
+
+  /**
+   * Follows the naming convention "theme-{blog,doc,version,page}?-<suffix>"
+   */
   docs: {
     docVersionBanner: 'theme-doc-version-banner',
     docVersionBadge: 'theme-doc-version-badge',

package/src/utils/docsUtils.tsx

@@ -324,7 +324,7 @@ export function useDocRouteMetadata({
     ? versionMetadata.docsSidebars[sidebarName]
     : undefined;
 
-  const docElement = renderRoutes(docRoutes, {versionMetadata});
+  const docElement = renderRoutes(docRoutes);
 
   return {
     docElement,

package/src/utils/historyUtils.ts

@@ -7,7 +7,7 @@
 
 import {useEffect} from 'react';
 import {useHistory} from '@docusaurus/router';
-import {useDynamicCallback} from './reactUtils';
+import {useEvent} from './reactUtils';
 import type {Location, Action} from 'history';
 
 type HistoryBlockHandler = (location: Location, action: Action) => void | false;
@@ -18,12 +18,12 @@ type HistoryBlockHandler = (location: Location, action: Action) => void | false;
  * will be blocked/cancelled.
  */
 function useHistoryActionHandler(handler: HistoryBlockHandler): void {
-  const {block} = useHistory();
-  const stableHandler = useDynamicCallback(handler);
+  const history = useHistory();
+  const stableHandler = useEvent(handler);
   useEffect(
     // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
-    () => block((location, action) => stableHandler(location, action)),
-    [block, stableHandler],
+    () => history.block((location, action) => stableHandler(location, action)),
+    [history, stableHandler],
   );
 }