@docusaurus/theme-common 2.4.0 → 3.0.0-alpha.0

package/src/components/ThemedComponent/index.tsx

@@ -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 React from 'react';
+import clsx from 'clsx';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import {useColorMode} from '../../contexts/colorMode';
+
+import styles from './styles.module.css';
+
+const AllThemes = ['light', 'dark'] as const;
+
+type Theme = (typeof AllThemes)[number];
+
+type RenderFn = ({
+  theme,
+  className,
+}: {
+  theme: Theme;
+  className: string;
+}) => React.ReactNode;
+
+type Props = {
+  children: RenderFn;
+  className?: string;
+};
+
+/**
+ * Generic component to render anything themed in light/dark
+ * Note: it's preferable to use CSS for theming because this component
+ * will need to render all the variants during SSR to avoid a theme flash.
+ *
+ * Use this only when CSS customizations are not convenient or impossible.
+ * For example, rendering themed images or SVGs...
+ *
+ * @param className applied to all the variants
+ * @param children function to render a theme variant
+ * @constructor
+ */
+export default function ThemedComponent({
+  className,
+  children,
+}: Props): JSX.Element {
+  const isBrowser = useIsBrowser();
+  const {colorMode} = useColorMode();
+
+  function getThemesToRender(): Theme[] {
+    if (isBrowser) {
+      return colorMode === 'dark' ? ['dark'] : ['light'];
+    }
+    // We need to render both components on the server / hydration to avoid:
+    // - a flash of wrong theme before hydration
+    // - React hydration mismatches
+    // See https://github.com/facebook/docusaurus/pull/3730
+    return ['light', 'dark'];
+  }
+
+  return (
+    <>
+      {getThemesToRender().map((theme) => {
+        const themedElement = children({
+          theme,
+          className: clsx(
+            className,
+            styles.themedComponent,
+            styles[`themedComponent--${theme}`],
+          ),
+        });
+        return <React.Fragment key={theme}>{themedElement}</React.Fragment>;
+      })}
+    </>
+  );
+}

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

@@ -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.
+ */
+
+.themedComponent {
+  display: none;
+}
+
+[data-theme='light'] .themedComponent--light {
+  display: initial;
+}
+
+[data-theme='dark'] .themedComponent--dark {
+  display: initial;
+}

package/src/contexts/blogPost.tsx

@@ -24,9 +24,9 @@ export type BlogPostContextValue = Pick<
 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.
+ * 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,

package/src/contexts/colorMode.tsx

@@ -41,7 +41,7 @@ const ColorModes = {
   dark: 'dark',
 } as const;
 
-export type ColorMode = typeof ColorModes[keyof typeof ColorModes];
+export type ColorMode = (typeof ColorModes)[keyof typeof ColorModes];
 
 // Ensure to always return a valid colorMode even if input is invalid
 const coerceToColorMode = (colorMode?: string | null): ColorMode =>

package/src/index.ts

@@ -24,6 +24,8 @@ export {
   type ColorModeConfig,
 } from './utils/useThemeConfig';
 
+export {default as ThemedComponent} from './components/ThemedComponent';
+
 export {
   createStorageSlot,
   useStorageSlot,
@@ -43,8 +45,9 @@ export {useCollapsible, Collapsible} from './components/Collapsible';
 
 export {ThemeClassNames} from './utils/ThemeClassNames';
 
+export {prefersReducedMotion} from './utils/accessibilityUtils';
+
 export {
-  useIsomorphicLayoutEffect,
   useEvent,
   usePrevious,
   composeProviders,
@@ -95,6 +98,12 @@ export {
   SkipToContentLink,
 } from './utils/skipToContentUtils';
 
+export {
+  UnlistedBannerTitle,
+  UnlistedBannerMessage,
+  UnlistedMetadata,
+} from './utils/unlistedUtils';
+
 export {
   ErrorBoundaryTryAgainButton,
   ErrorBoundaryError,

package/src/internal.ts

@@ -42,7 +42,7 @@ export {
   useAnnouncementBar,
 } from './contexts/announcementBar';
 
-export {useTabs} from './utils/tabsUtils';
+export {useTabs, sanitizeTabsChildren} from './utils/tabsUtils';
 export type {TabValue, TabsProps, TabItemProps} from './utils/tabsUtils';
 
 export {useNavbarMobileSidebar} from './contexts/navbarMobileSidebar';
@@ -65,13 +65,15 @@ export {
   isDocsPluginEnabled,
   useDocById,
   findSidebarCategory,
-  findFirstCategoryLink,
+  findFirstSidebarItemLink,
   isActiveSidebarItem,
+  isVisibleSidebarItem,
+  useVisibleSidebarItems,
   useSidebarBreadcrumbs,
   useDocsVersionCandidates,
   useLayoutDoc,
   useLayoutDocsSidebar,
-  useDocRouteMetadata,
+  useDocRootMetadata,
 } from './utils/docsUtils';
 
 export {useTitleFormatter} from './utils/generalUtils';
@@ -111,6 +113,8 @@ export {
   type TOCHighlightConfig,
 } from './hooks/useTOCHighlight';
 
+export {useVisibleBlogSidebarItems} from './utils/blogUtils';
+
 export {useHideableNavbar} from './hooks/useHideableNavbar';
 export {
   useKeyboardNavigation,

package/src/utils/ThemeClassNames.ts

@@ -27,6 +27,9 @@ export const ThemeClassNames = {
   },
   wrapper: {
     main: 'main-wrapper',
+    // TODO these wrapper class names are now quite useless
+    // TODO do breaking change later in 3.0
+    // we already add plugin name/id class on <html>: that's enough
     blogPages: 'blog-wrapper',
     docsPages: 'docs-wrapper',
     mdxPages: 'mdx-wrapper',
@@ -37,8 +40,9 @@ export const ThemeClassNames = {
     backToTopButton: 'theme-back-to-top-button',
     codeBlock: 'theme-code-block',
     admonition: 'theme-admonition',
-    admonitionType: (type: 'note' | 'tip' | 'danger' | 'info' | 'caution') =>
-      `theme-admonition-${type}`,
+    unlistedBanner: 'theme-unlisted-banner',
+
+    admonitionType: (type: string) => `theme-admonition-${type}`,
   },
   layout: {
     // TODO add other stable classNames here

package/src/utils/accessibilityUtils.ts

@@ -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.
+ */
+
+export function prefersReducedMotion(): boolean {
+  return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+}

package/src/utils/admonitionUtils.tsx

@@ -14,16 +14,17 @@ function extractMDXAdmonitionTitle(children: ReactNode): {
   rest: ReactNode;
 } {
   const items = React.Children.toArray(children);
-  const mdxAdmonitionTitle = items.find(
-    (item) =>
-      React.isValidElement(item) &&
-      (item.props as {mdxType: string} | null)?.mdxType ===
-        'mdxAdmonitionTitle',
+  const mdxAdmonitionTitleWrapper = items.find(
+    (item) => React.isValidElement(item) && item.type === 'mdxAdmonitionTitle',
   ) as JSX.Element | undefined;
-  const rest = <>{items.filter((item) => item !== mdxAdmonitionTitle)}</>;
+
+  const rest = items.filter((item) => item !== mdxAdmonitionTitleWrapper);
+
+  const mdxAdmonitionTitle = mdxAdmonitionTitleWrapper?.props.children;
+
   return {
-    mdxAdmonitionTitle: mdxAdmonitionTitle?.props.children,
-    rest,
+    mdxAdmonitionTitle,
+    rest: rest.length > 0 ? <>{rest}</> : null,
   };
 }
 

package/src/utils/blogUtils.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 {useMemo} from 'react';
+import {useLocation} from '@docusaurus/router';
+import {isSamePath} from './routesUtils';
+import type {BlogSidebarItem} from '@docusaurus/plugin-content-blog';
+
+function isVisible(item: BlogSidebarItem, pathname: string): boolean {
+  if (item.unlisted && !isSamePath(item.permalink, pathname)) {
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Return the visible blog sidebar items to display.
+ * Unlisted items are filtered.
+ */
+export function useVisibleBlogSidebarItems(
+  items: BlogSidebarItem[],
+): BlogSidebarItem[] {
+  const {pathname} = useLocation();
+  return useMemo(
+    () => items.filter((item) => isVisible(item, pathname)),
+    [items, pathname],
+  );
+}

package/src/utils/codeBlockUtils.ts

@@ -19,6 +19,9 @@ const commentPatterns = {
   jsx: {start: '\\{\\s*\\/\\*', end: '\\*\\/\\s*\\}'},
   bash: {start: '#', end: ''},
   html: {start: '<!--', end: '-->'},
+  lua: {start: '--', end: ''},
+  wasm: {start: '\\;\\;', end: ''},
+  tex: {start: '%', end: ''},
 };
 
 type CommentType = keyof typeof commentPatterns;
@@ -83,10 +86,26 @@ function getAllMagicCommentDirectiveStyles(
       // Text uses HTML, front matter uses bash
       return getCommentPattern(['html', 'jsx', 'bash'], magicCommentDirectives);
 
+    case 'tex':
+    case 'latex':
+    case 'matlab':
+      return getCommentPattern(['tex'], magicCommentDirectives);
+
+    case 'lua':
+    case 'haskell':
+    case 'sql':
+      return getCommentPattern(['lua'], magicCommentDirectives);
+
+    case 'wasm':
+      return getCommentPattern(['wasm'], magicCommentDirectives);
+
     default:
-      // All comment types
+      // All comment types except lua, wasm and matlab
       return getCommentPattern(
-        Object.keys(commentPatterns) as CommentType[],
+        Object.keys(commentPatterns).filter(
+          (pattern) =>
+            !['lua', 'wasm', 'tex', 'latex', 'matlab'].includes(pattern),
+        ) as CommentType[],
         magicCommentDirectives,
       );
   }

package/src/utils/docsUtils.tsx

@@ -17,7 +17,7 @@ import {
   type GlobalSidebar,
   type GlobalDoc,
 } from '@docusaurus/plugin-content-docs/client';
-import type {Props as DocPageProps} from '@theme/DocPage';
+import type {Props as DocRootProps} from '@theme/DocRoot';
 import {useDocsPreferredVersion} from '../contexts/docsPreferredVersion';
 import {useDocsVersion} from '../contexts/docsVersion';
 import {useDocsSidebar} from '../contexts/docsSidebar';
@@ -79,27 +79,38 @@ export function findSidebarCategory(
  * Best effort to assign a link to a sidebar category. If the category doesn't
  * have a link itself, we link to the first sub item with a link.
  */
-export function findFirstCategoryLink(
+export function findFirstSidebarItemCategoryLink(
   item: PropSidebarItemCategory,
 ): string | undefined {
-  if (item.href) {
+  if (item.href && !item.linkUnlisted) {
     return item.href;
   }
 
   for (const subItem of item.items) {
-    if (subItem.type === 'link') {
-      return subItem.href;
-    } else if (subItem.type === 'category') {
-      const categoryLink = findFirstCategoryLink(subItem);
-      if (categoryLink) {
-        return categoryLink;
-      }
+    const link = findFirstSidebarItemLink(subItem);
+    if (link) {
+      return link;
     }
-    // Could be "html" items
   }
   return undefined;
 }
 
+/**
+ * Best effort to assign a link to a sidebar item.
+ */
+export function findFirstSidebarItemLink(
+  item: PropSidebarItem,
+): string | undefined {
+  if (item.type === 'link' && !item.unlisted) {
+    return item.href;
+  }
+  if (item.type === 'category') {
+    return findFirstSidebarItemCategoryLink(item);
+  }
+  // Other items types, like "html"
+  return undefined;
+}
+
 /**
  * Gets the category associated with the current location. Should only be used
  * on category index pages.
@@ -152,6 +163,34 @@ export function isActiveSidebarItem(
   return false;
 }
 
+export function isVisibleSidebarItem(
+  item: PropSidebarItem,
+  activePath: string,
+): boolean {
+  switch (item.type) {
+    case 'category':
+      return (
+        isActiveSidebarItem(item, activePath) ||
+        item.items.some((subItem) => isVisibleSidebarItem(subItem, activePath))
+      );
+    case 'link':
+      // An unlisted item remains visible if it is active
+      return !item.unlisted || isActiveSidebarItem(item, activePath);
+    default:
+      return false;
+  }
+}
+
+export function useVisibleSidebarItems(
+  items: readonly PropSidebarItem[],
+  activePath: string,
+): PropSidebarItem[] {
+  return useMemo(
+    () => items.filter((item) => isVisibleSidebarItem(item, activePath)),
+    [items, activePath],
+  );
+}
+
 function getSidebarBreadcrumbs(param: {
   sidebarItems: PropSidebar;
   pathname: string;
@@ -272,7 +311,7 @@ export function useLayoutDocsSidebar(
           versions.length > 1 ? 's' : ''
         } ${versions.map((version) => version.name).join(', ')}".
 Available sidebar ids are:
-- ${Object.keys(allSidebars).join('\n- ')}`,
+- ${allSidebars.map((entry) => entry[0]).join('\n- ')}`,
       );
     }
     return sidebarEntry[1];
@@ -321,14 +360,11 @@ Available doc ids are:
  * version metadata, and the subroutes creating individual doc pages. This hook
  * will match the current location against all known sub-routes.
  *
- * @param props The props received by `@theme/DocPage`
+ * @param props The props received by `@theme/DocRoot`
  * @returns The data of the relevant document at the current location, or `null`
  * if no document associated with the current location can be found.
  */
-export function useDocRouteMetadata({
-  route,
-  versionMetadata,
-}: DocPageProps): null | {
+export function useDocRootMetadata({route}: DocRootProps): null | {
   /** The element that should be rendered at the current location. */
   docElement: JSX.Element;
   /**
@@ -340,6 +376,7 @@ export function useDocRouteMetadata({
   sidebarItems: PropSidebar | undefined;
 } {
   const location = useLocation();
+  const versionMetadata = useDocsVersion();
   const docRoutes = route.routes!;
   const currentDocRoute = docRoutes.find((docRoute) =>
     matchPath(location.pathname, docRoute),
@@ -365,15 +402,16 @@ export function useDocRouteMetadata({
 }
 
 /**
- * Filter categories that don't have a link.
+ * Filter items we don't want to display on the doc card list view
  * @param items
  */
 export function filterDocCardListItems(
   items: PropSidebarItem[],
 ): PropSidebarItem[] {
   return items.filter((item) => {
-    if (item.type === 'category') {
-      return !!findFirstCategoryLink(item);
+    const canHaveLink = item.type === 'category' || item.type === 'link';
+    if (canHaveLink) {
+      return !!findFirstSidebarItemLink(item);
     }
     return true;
   });

package/src/utils/reactUtils.tsx

@@ -7,26 +7,12 @@
 
 import React, {
   useCallback,
-  useEffect,
-  useLayoutEffect,
   useMemo,
   useRef,
   type ComponentType,
   type ReactNode,
 } from 'react';
-import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
-
-/**
- * This hook is like `useLayoutEffect`, but without the SSR warning.
- * It seems hacky but it's used in many React libs (Redux, Formik...).
- * Also mentioned here: https://github.com/facebook/react/issues/16956
- *
- * It is useful when you need to update a ref as soon as possible after a React
- * render (before `useEffect`).
- */
-export const useIsomorphicLayoutEffect = ExecutionEnvironment.canUseDOM
-  ? useLayoutEffect
-  : useEffect;
+import useIsomorphicLayoutEffect from '@docusaurus/useIsomorphicLayoutEffect';
 
 /**
  * Temporary userland implementation until an official hook is implemented

package/src/utils/scrollUtils.tsx

@@ -9,13 +9,13 @@ import React, {
   useCallback,
   useContext,
   useEffect,
-  useLayoutEffect,
   useMemo,
   useRef,
   type ReactNode,
 } from 'react';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import useIsBrowser from '@docusaurus/useIsBrowser';
+import useIsomorphicLayoutEffect from '@docusaurus/useIsomorphicLayoutEffect';
 import {useEvent, ReactContextError} from './reactUtils';
 
 type ScrollController = {
@@ -221,7 +221,7 @@ export function useScrollPositionBlocker(): {
     [scrollController, scrollPositionSaver],
   );
 
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     // 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

package/src/utils/skipToContentUtils.tsx

@@ -14,8 +14,11 @@ 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';
+export const SkipToContentFallbackId = '__docusaurus_skipToContent_fallback';
 
 /**
  * Returns the skip to content element to focus when the link is clicked.
@@ -90,6 +93,7 @@ export function SkipToContentLink(props: SkipToContentLinkProps): JSX.Element {
       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

package/src/utils/storageUtils.ts

@@ -11,7 +11,7 @@ import {useSyncExternalStore} from 'use-sync-external-store/shim';
 
 const StorageTypes = ['localStorage', 'sessionStorage', 'none'] as const;
 
-export type StorageType = typeof StorageTypes[number];
+export type StorageType = (typeof StorageTypes)[number];
 
 const DefaultStorageType: StorageType = 'localStorage';
 

package/src/utils/tabsUtils.tsx

@@ -12,9 +12,9 @@ import React, {
   useMemo,
   type ReactNode,
   type ReactElement,
-  useLayoutEffect,
 } from 'react';
 import {useHistory} from '@docusaurus/router';
+import useIsomorphicLayoutEffect from '@docusaurus/useIsomorphicLayoutEffect';
 import {useQueryStringValue} from '@docusaurus/theme-common/internal';
 import {duplicates, useStorageSlot} from '../index';
 
@@ -61,25 +61,27 @@ function isTabItem(
   return !!props && typeof props === 'object' && 'value' in props;
 }
 
-function ensureValidChildren(children: TabsProps['children']) {
-  return (React.Children.map(children, (child) => {
-    // Pass falsy values through: allow conditionally not rendering a tab
-    if (!child || (isValidElement(child) && isTabItem(child))) {
-      return child;
-    }
-    // child.type.name will give non-sensical values in prod because of
-    // minification, but we assume it won't throw in prod.
-    throw new Error(
-      `Docusaurus error: Bad <Tabs> child <${
-        // @ts-expect-error: guarding against unexpected cases
-        typeof child.type === 'string' ? child.type : child.type.name
-      }>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`,
-    );
-  })?.filter(Boolean) ?? []) as ReactElement<TabItemProps>[];
+export function sanitizeTabsChildren(children: TabsProps['children']) {
+  return (React.Children.toArray(children)
+    .filter((child) => child !== '\n')
+    .map((child) => {
+      if (!child || (isValidElement(child) && isTabItem(child))) {
+        return child;
+      }
+      // child.type.name will give non-sensical values in prod because of
+      // minification, but we assume it won't throw in prod.
+      throw new Error(
+        `Docusaurus error: Bad <Tabs> child <${
+          // @ts-expect-error: guarding against unexpected cases
+          typeof child.type === 'string' ? child.type : child.type.name
+        }>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`,
+      );
+    })
+    ?.filter(Boolean) ?? []) as ReactElement<TabItemProps>[];
 }
 
 function extractChildrenTabValues(children: TabsProps['children']): TabValue[] {
-  return ensureValidChildren(children).map(
+  return sanitizeTabsChildren(children).map(
     ({props: {value, label, attributes, default: isDefault}}) => ({
       value,
       label,
@@ -250,7 +252,7 @@ export function useTabs(props: TabsProps): {
   })();
   // Sync in a layout/sync effect is important, for useScrollPositionBlocker
   // See https://github.com/facebook/docusaurus/issues/8625
-  useLayoutEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     if (valueToSync) {
       setSelectedValue(valueToSync);
     }

package/src/utils/unlistedUtils.tsx

@@ -0,0 +1,39 @@
+/**
+ * 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 from 'react';
+import Translate from '@docusaurus/Translate';
+import Head from '@docusaurus/Head';
+
+export function UnlistedBannerTitle(): JSX.Element {
+  return (
+    <Translate
+      id="theme.unlistedContent.title"
+      description="The unlisted content banner title">
+      Unlisted page
+    </Translate>
+  );
+}
+
+export function UnlistedBannerMessage(): JSX.Element {
+  return (
+    <Translate
+      id="theme.unlistedContent.message"
+      description="The unlisted content banner message">
+      This page is unlisted. Search engines will not index it, and only users
+      having a direct link can access it.
+    </Translate>
+  );
+}
+
+export function UnlistedMetadata(): JSX.Element {
+  return (
+    <Head>
+      <meta name="robots" content="noindex, nofollow" />
+    </Head>
+  );
+}