@docusaurus/theme-classic 3.7.0 → 3.8.0

package/src/theme/NavbarItem/DropdownNavbarItem/index.tsx

@@ -5,174 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useState, useRef, useEffect, type ReactNode} from 'react';
-import clsx from 'clsx';
-import {
-  isRegexpStringMatch,
-  useCollapsible,
-  Collapsible,
-} from '@docusaurus/theme-common';
-import {isSamePath, useLocalPathname} from '@docusaurus/theme-common/internal';
-import NavbarNavLink from '@theme/NavbarItem/NavbarNavLink';
-import NavbarItem, {type LinkLikeNavbarItemProps} from '@theme/NavbarItem';
-import type {
-  DesktopOrMobileNavBarItemProps,
-  Props,
-} from '@theme/NavbarItem/DropdownNavbarItem';
-import styles from './styles.module.css';
-
-function isItemActive(
-  item: LinkLikeNavbarItemProps,
-  localPathname: string,
-): boolean {
-  if (isSamePath(item.to, localPathname)) {
-    return true;
-  }
-  if (isRegexpStringMatch(item.activeBaseRegex, localPathname)) {
-    return true;
-  }
-  if (item.activeBasePath && localPathname.startsWith(item.activeBasePath)) {
-    return true;
-  }
-  return false;
-}
-
-function containsActiveItems(
-  items: readonly LinkLikeNavbarItemProps[],
-  localPathname: string,
-): boolean {
-  return items.some((item) => isItemActive(item, localPathname));
-}
-
-function DropdownNavbarItemDesktop({
-  items,
-  position,
-  className,
-  onClick,
-  ...props
-}: DesktopOrMobileNavBarItemProps) {
-  const dropdownRef = useRef<HTMLDivElement>(null);
-  const [showDropdown, setShowDropdown] = useState(false);
-
-  useEffect(() => {
-    const handleClickOutside = (
-      event: MouseEvent | TouchEvent | FocusEvent,
-    ) => {
-      if (
-        !dropdownRef.current ||
-        dropdownRef.current.contains(event.target as Node)
-      ) {
-        return;
-      }
-      setShowDropdown(false);
-    };
-
-    document.addEventListener('mousedown', handleClickOutside);
-    document.addEventListener('touchstart', handleClickOutside);
-    document.addEventListener('focusin', handleClickOutside);
-
-    return () => {
-      document.removeEventListener('mousedown', handleClickOutside);
-      document.removeEventListener('touchstart', handleClickOutside);
-      document.removeEventListener('focusin', handleClickOutside);
-    };
-  }, [dropdownRef]);
-
-  return (
-    <div
-      ref={dropdownRef}
-      className={clsx('navbar__item', 'dropdown', 'dropdown--hoverable', {
-        'dropdown--right': position === 'right',
-        'dropdown--show': showDropdown,
-      })}>
-      <NavbarNavLink
-        aria-haspopup="true"
-        aria-expanded={showDropdown}
-        role="button"
-        // # hash permits to make the <a> tag focusable in case no link target
-        // See https://github.com/facebook/docusaurus/pull/6003
-        // There's probably a better solution though...
-        href={props.to ? undefined : '#'}
-        className={clsx('navbar__link', className)}
-        {...props}
-        onClick={props.to ? undefined : (e) => e.preventDefault()}
-        onKeyDown={(e) => {
-          if (e.key === 'Enter') {
-            e.preventDefault();
-            setShowDropdown(!showDropdown);
-          }
-        }}>
-        {props.children ?? props.label}
-      </NavbarNavLink>
-      <ul className="dropdown__menu">
-        {items.map((childItemProps, i) => (
-          <NavbarItem
-            isDropdownItem
-            activeClassName="dropdown__link--active"
-            {...childItemProps}
-            key={i}
-          />
-        ))}
-      </ul>
-    </div>
-  );
-}
-
-function DropdownNavbarItemMobile({
-  items,
-  className,
-  position, // Need to destructure position from props so that it doesn't get passed on.
-  onClick,
-  ...props
-}: DesktopOrMobileNavBarItemProps) {
-  const localPathname = useLocalPathname();
-  const containsActive = containsActiveItems(items, localPathname);
-
-  const {collapsed, toggleCollapsed, setCollapsed} = useCollapsible({
-    initialState: () => !containsActive,
-  });
-
-  // Expand/collapse if any item active after a navigation
-  useEffect(() => {
-    if (containsActive) {
-      setCollapsed(!containsActive);
-    }
-  }, [localPathname, containsActive, setCollapsed]);
-
-  return (
-    <li
-      className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
-      })}>
-      <NavbarNavLink
-        role="button"
-        className={clsx(
-          styles.dropdownNavbarItemMobile,
-          'menu__link menu__link--sublist menu__link--sublist-caret',
-          className,
-        )}
-        {...props}
-        onClick={(e) => {
-          e.preventDefault();
-          toggleCollapsed();
-        }}>
-        {props.children ?? props.label}
-      </NavbarNavLink>
-      <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
-        {items.map((childItemProps, i) => (
-          <NavbarItem
-            mobile
-            isDropdownItem
-            onClick={onClick}
-            activeClassName="menu__link--active"
-            {...childItemProps}
-            key={i}
-          />
-        ))}
-      </Collapsible>
-    </li>
-  );
-}
+import React, {type ReactNode} from 'react';
+import DropdownNavbarItemMobile from '@theme/NavbarItem/DropdownNavbarItem/Mobile';
+import DropdownNavbarItemDesktop from '@theme/NavbarItem/DropdownNavbarItem/Desktop';
+import type {Props} from '@theme/NavbarItem/DropdownNavbarItem';
 
 export default function DropdownNavbarItem({
   mobile = false,

package/src/theme/Tag/index.tsx

@@ -20,6 +20,7 @@ export default function Tag({
 }: Props): ReactNode {
   return (
     <Link
+      rel="tag"
       href={permalink}
       title={description}
       className={clsx(

package/src/theme/ThemeProvider/TitleFormatter/index.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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 ReactNode} from 'react';
+import {TitleFormatterProvider} from '@docusaurus/theme-common/internal';
+import type {Props} from '@theme/ThemeProvider/TitleFormatter';
+
+type FormatterProp = ComponentProps<typeof TitleFormatterProvider>['formatter'];
+
+const formatter: FormatterProp = (params) => {
+  // Add your own title formatting logic here!
+  return params.defaultFormatter(params);
+};
+
+export default function ThemeProviderTitleFormatter({
+  children,
+}: Props): ReactNode {
+  return (
+    <TitleFormatterProvider formatter={formatter}>
+      {children}
+    </TitleFormatterProvider>
+  );
+}

package/src/theme/ThemeProvider/index.tsx

@@ -0,0 +1,14 @@
+/**
+ * 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 ReactNode} from 'react';
+import TitleFormatterProvider from '@theme/ThemeProvider/TitleFormatter';
+import type {Props} from '@theme/ThemeProvider';
+
+export default function ThemeProvider({children}: Props): ReactNode {
+  return <TitleFormatterProvider>{children}</TitleFormatterProvider>;
+}

package/src/theme-classic.d.ts

@@ -410,9 +410,9 @@ declare module '@theme/CodeBlock' {
     readonly children: ReactNode;
     readonly className?: string;
     readonly metastring?: string;
-    readonly title?: string;
+    readonly title?: ReactNode;
     readonly language?: string;
-    readonly showLineNumbers?: boolean;
+    readonly showLineNumbers?: boolean | number;
   }
 
   export default function CodeBlock(props: Props): ReactNode;
@@ -426,17 +426,76 @@ declare module '@theme/CodeInline' {
   export default function CodeInline(props: Props): ReactNode;
 }
 
-declare module '@theme/CodeBlock/CopyButton' {
+declare module '@theme/CodeBlock/Provider' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+
+  export default function CodeBlockProvider(props: Props): ReactNode;
+}
+
+declare module '@theme/CodeBlock/Title' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+
+  export default function CodeBlockTitle(props: Props): ReactNode;
+}
+
+declare module '@theme/CodeBlock/Layout' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly className?: string;
+  }
+
+  export default function CodeBlockLayout(props: Props): ReactNode;
+}
+
+declare module '@theme/CodeBlock/Buttons' {
   import type {ReactNode} from 'react';
 
   export interface Props {
-    readonly code: string;
+    readonly className?: string;
+  }
+
+  export default function CodeBlockButtons(props: Props): ReactNode;
+}
+
+declare module '@theme/CodeBlock/Buttons/Button' {
+  import type {ComponentProps, ReactNode} from 'react';
+
+  export interface Props extends ComponentProps<'button'> {
     readonly className?: string;
   }
 
   export default function CopyButton(props: Props): ReactNode;
 }
 
+declare module '@theme/CodeBlock/Buttons/CopyButton' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly className?: string;
+  }
+
+  export default function CodeBlockButtonCopy(props: Props): ReactNode;
+}
+
+declare module '@theme/CodeBlock/Buttons/WordWrapButton' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly className?: string;
+  }
+
+  export default function CodeBlockButtonWordWrap(props: Props): ReactNode;
+}
+
 declare module '@theme/CodeBlock/Container' {
   import type {ReactNode} from 'react';
   import type {ComponentProps} from 'react';
@@ -447,13 +506,23 @@ declare module '@theme/CodeBlock/Container' {
   }: {as: T} & ComponentProps<T>): ReactNode;
 }
 
+declare module '@theme/CodeBlock/Content' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    className?: string;
+  }
+
+  export default function CodeBlockContent(props: Props): ReactNode;
+}
+
 declare module '@theme/CodeBlock/Content/Element' {
   import type {ReactNode} from 'react';
   import type {Props} from '@theme/CodeBlock';
 
   export type {Props};
 
-  export default function CodeBlockElementContent(props: Props): ReactNode;
+  export default function CodeBlockContentElement(props: Props): ReactNode;
 }
 
 declare module '@theme/CodeBlock/Content/String' {
@@ -464,7 +533,7 @@ declare module '@theme/CodeBlock/Content/String' {
     readonly children: string;
   }
 
-  export default function CodeBlockStringContent(props: Props): ReactNode;
+  export default function CodeBlockContentString(props: Props): ReactNode;
 }
 
 declare module '@theme/CodeBlock/Line' {
@@ -488,16 +557,16 @@ declare module '@theme/CodeBlock/Line' {
   export default function CodeBlockLine(props: Props): ReactNode;
 }
 
-declare module '@theme/CodeBlock/WordWrapButton' {
+declare module '@theme/CodeBlock/Line/Token' {
   import type {ReactNode} from 'react';
+  import type {Token, TokenOutputProps} from 'prism-react-renderer';
 
-  export interface Props {
-    readonly className?: string;
-    readonly onClick: React.MouseEventHandler;
-    readonly isEnabled: boolean;
+  export interface Props extends TokenOutputProps {
+    readonly token: Token;
+    readonly line: Token[];
   }
 
-  export default function WordWrapButton(props: Props): ReactNode;
+  export default function CodeBlockLine(props: Props): ReactNode;
 }
 
 declare module '@theme/DocCard' {
@@ -624,7 +693,9 @@ declare module '@theme/DocPaginator' {
   import type {PropNavigation} from '@docusaurus/plugin-content-docs';
 
   // May be simpler to provide a {navigation: PropNavigation} prop?
-  export interface Props extends PropNavigation {}
+  export interface Props extends PropNavigation {
+    className?: string;
+  }
 
   export default function DocPaginator(props: Props): ReactNode;
 }
@@ -1179,19 +1250,40 @@ declare module '@theme/NavbarItem/DefaultNavbarItem' {
   import type {ReactNode} from 'react';
   import type {Props as NavbarNavLinkProps} from '@theme/NavbarItem/NavbarNavLink';
 
-  export type DesktopOrMobileNavBarItemProps = NavbarNavLinkProps & {
+  export type DefaultNavbarItemProps = NavbarNavLinkProps & {
     readonly isDropdownItem?: boolean;
     readonly className?: string;
     readonly position?: 'left' | 'right';
   };
 
-  export interface Props extends DesktopOrMobileNavBarItemProps {
+  // TODO Docusaurus v4, remove old type name
+  export type DesktopOrMobileNavBarItemProps = DefaultNavbarItemProps;
+
+  export interface Props extends DefaultNavbarItemProps {
     readonly mobile?: boolean;
   }
 
   export default function DefaultNavbarItem(props: Props): ReactNode;
 }
 
+declare module '@theme/NavbarItem/DefaultNavbarItem/Mobile' {
+  import type {ReactNode} from 'react';
+  import type {DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
+
+  export interface Props extends DefaultNavbarItemProps {}
+
+  export default function DefaultNavbarItemMobile(props: Props): ReactNode;
+}
+
+declare module '@theme/NavbarItem/DefaultNavbarItem/Desktop' {
+  import type {ReactNode} from 'react';
+  import type {DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
+
+  export interface Props extends DefaultNavbarItemProps {}
+
+  export default function DefaultNavbarItemDesktop(props: Props): ReactNode;
+}
+
 declare module '@theme/NavbarItem/NavbarNavLink' {
   import type {ReactNode} from 'react';
   import type {Props as LinkProps} from '@docusaurus/Link';
@@ -1214,19 +1306,40 @@ declare module '@theme/NavbarItem/DropdownNavbarItem' {
   import type {Props as NavbarNavLinkProps} from '@theme/NavbarItem/NavbarNavLink';
   import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 
-  export type DesktopOrMobileNavBarItemProps = NavbarNavLinkProps & {
+  export type DropdownNavbarItemProps = NavbarNavLinkProps & {
     readonly position?: 'left' | 'right';
     readonly items: readonly LinkLikeNavbarItemProps[];
     readonly className?: string;
   };
 
-  export interface Props extends DesktopOrMobileNavBarItemProps {
+  // TODO Docusaurus v4, remove old type name
+  export type DesktopOrMobileNavBarItemProps = DropdownNavbarItemProps;
+
+  export interface Props extends DropdownNavbarItemProps {
     readonly mobile?: boolean;
   }
 
   export default function DropdownNavbarItem(props: Props): ReactNode;
 }
 
+declare module '@theme/NavbarItem/DropdownNavbarItem/Mobile' {
+  import type {ReactNode} from 'react';
+  import type {DropdownNavbarItemProps} from '@theme/NavbarItem/DropdownNavbarItem';
+
+  export interface Props extends DropdownNavbarItemProps {}
+
+  export default function DropdownNavbarItemMobile(props: Props): ReactNode;
+}
+
+declare module '@theme/NavbarItem/DropdownNavbarItem/Desktop' {
+  import type {ReactNode} from 'react';
+  import type {DropdownNavbarItemProps} from '@theme/NavbarItem/DropdownNavbarItem';
+
+  export interface Props extends DropdownNavbarItemProps {}
+
+  export default function DropdownNavbarItemDesktop(props: Props): ReactNode;
+}
+
 declare module '@theme/NavbarItem/SearchNavbarItem' {
   import type {ReactNode} from 'react';
 
@@ -1257,11 +1370,22 @@ declare module '@theme/NavbarItem/DocsVersionDropdownNavbarItem' {
   import type {Props as DropdownNavbarItemProps} from '@theme/NavbarItem/DropdownNavbarItem';
   import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 
+  type PropVersionItem = {
+    readonly label?: string;
+  };
+
+  type PropVersionItems = {
+    readonly [version: string]: PropVersionItem;
+  };
+
+  type PropVersions = string[] | PropVersionItems;
+
   export interface Props extends DropdownNavbarItemProps {
     readonly docsPluginId?: string;
     readonly dropdownActiveClassDisabled?: boolean;
     readonly dropdownItemsBefore: LinkLikeNavbarItemProps[];
     readonly dropdownItemsAfter: LinkLikeNavbarItemProps[];
+    readonly versions?: PropVersions;
   }
 
   export default function DocsVersionDropdownNavbarItem(
@@ -1445,6 +1569,17 @@ declare module '@theme/ThemedImage' {
   export default function ThemedImage(props: Props): ReactNode;
 }
 
+declare module '@theme/ThemeProvider/TitleFormatter' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+  export default function ThemeProviderTitleFormatter({
+    children,
+  }: Props): ReactNode;
+}
+
 declare module '@theme/Details' {
   import {Details, type DetailsProps} from '@docusaurus/theme-common/Details';
 
@@ -1542,12 +1677,13 @@ declare module '@theme/ColorModeToggle' {
   export interface Props {
     readonly className?: string;
     readonly buttonClassName?: string;
-    readonly value: ColorMode;
+    readonly respectPrefersColorScheme: boolean;
+    readonly value: ColorMode | null;
     /**
      * The parameter represents the "to-be" value. For example, if currently in
-     * dark mode, clicking the button should call `onChange("light")`
+     * light mode, clicking the button should call `onChange("dark")`
      */
-    readonly onChange: (colorMode: ColorMode) => void;
+    readonly onChange: (colorMode: ColorMode | null) => void;
   }
 
   export default function ColorModeToggle(props: Props): ReactNode;
@@ -1604,6 +1740,14 @@ declare module '@theme/Icon/LightMode' {
   export default function IconLightMode(props: Props): ReactNode;
 }
 
+declare module '@theme/Icon/SystemColorMode' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function IconSystemColorMode(props: Props): JSX.Element;
+}
+
 declare module '@theme/Icon/Menu' {
   import type {ComponentProps, ReactNode} from 'react';
 
@@ -1833,3 +1977,14 @@ declare module '@theme/DocBreadcrumbs/Items/Home' {
 
   export default function HomeBreadcrumbItem(): ReactNode;
 }
+
+declare module '@theme/DocBreadcrumbs/StructuredData' {
+  import type {ReactNode} from 'react';
+  import type {PropSidebarBreadcrumbsItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly breadcrumbs: PropSidebarBreadcrumbsItem[];
+  }
+
+  export default function DocBreadcrumbsStructuredData(props: Props): ReactNode;
+}

package/lib/theme/NavbarItem/DefaultNavbarItem.js

@@ -1,52 +0,0 @@
-/**
- * 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 NavbarNavLink from '@theme/NavbarItem/NavbarNavLink';
-function DefaultNavbarItemDesktop({
-  className,
-  isDropdownItem = false,
-  ...props
-}) {
-  const element = (
-    <NavbarNavLink
-      className={clsx(
-        isDropdownItem ? 'dropdown__link' : 'navbar__item navbar__link',
-        className,
-      )}
-      isDropdownLink={isDropdownItem}
-      {...props}
-    />
-  );
-  if (isDropdownItem) {
-    return <li>{element}</li>;
-  }
-  return element;
-}
-function DefaultNavbarItemMobile({className, isDropdownItem, ...props}) {
-  return (
-    <li className="menu__list-item">
-      <NavbarNavLink className={clsx('menu__link', className)} {...props} />
-    </li>
-  );
-}
-export default function DefaultNavbarItem({
-  mobile = false,
-  position, // Need to destructure position from props so that it doesn't get passed on.
-  ...props
-}) {
-  const Comp = mobile ? DefaultNavbarItemMobile : DefaultNavbarItemDesktop;
-  return (
-    <Comp
-      {...props}
-      activeClassName={
-        props.activeClassName ??
-        (mobile ? 'menu__link--active' : 'navbar__link--active')
-      }
-    />
-  );
-}

package/src/theme/NavbarItem/DefaultNavbarItem.tsx

@@ -1,66 +0,0 @@
-/**
- * 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 ReactNode} from 'react';
-import clsx from 'clsx';
-import NavbarNavLink from '@theme/NavbarItem/NavbarNavLink';
-import type {
-  DesktopOrMobileNavBarItemProps,
-  Props,
-} from '@theme/NavbarItem/DefaultNavbarItem';
-
-function DefaultNavbarItemDesktop({
-  className,
-  isDropdownItem = false,
-  ...props
-}: DesktopOrMobileNavBarItemProps) {
-  const element = (
-    <NavbarNavLink
-      className={clsx(
-        isDropdownItem ? 'dropdown__link' : 'navbar__item navbar__link',
-        className,
-      )}
-      isDropdownLink={isDropdownItem}
-      {...props}
-    />
-  );
-
-  if (isDropdownItem) {
-    return <li>{element}</li>;
-  }
-
-  return element;
-}
-
-function DefaultNavbarItemMobile({
-  className,
-  isDropdownItem,
-  ...props
-}: DesktopOrMobileNavBarItemProps) {
-  return (
-    <li className="menu__list-item">
-      <NavbarNavLink className={clsx('menu__link', className)} {...props} />
-    </li>
-  );
-}
-
-export default function DefaultNavbarItem({
-  mobile = false,
-  position, // Need to destructure position from props so that it doesn't get passed on.
-  ...props
-}: Props): ReactNode {
-  const Comp = mobile ? DefaultNavbarItemMobile : DefaultNavbarItemDesktop;
-  return (
-    <Comp
-      {...props}
-      activeClassName={
-        props.activeClassName ??
-        (mobile ? 'menu__link--active' : 'navbar__link--active')
-      }
-    />
-  );
-}