@docusaurus/theme-classic 3.7.0 → 3.8.0-canary-6324

package/lib/theme/NavbarItem/DropdownNavbarItem/Mobile/index.js

@@ -0,0 +1,142 @@
+/**
+ * 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, {useEffect} from 'react';
+import clsx from 'clsx';
+import {
+  isRegexpStringMatch,
+  useCollapsible,
+  Collapsible,
+} from '@docusaurus/theme-common';
+import {isSamePath, useLocalPathname} from '@docusaurus/theme-common/internal';
+import {translate} from '@docusaurus/Translate';
+import NavbarNavLink from '@theme/NavbarItem/NavbarNavLink';
+import NavbarItem from '@theme/NavbarItem';
+import styles from './styles.module.css';
+function isItemActive(item, localPathname) {
+  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, localPathname) {
+  return items.some((item) => isItemActive(item, localPathname));
+}
+function CollapseButton({collapsed, onClick}) {
+  return (
+    <button
+      aria-label={
+        collapsed
+          ? translate({
+              id: 'theme.navbar.mobileDropdown.collapseButton.expandAriaLabel',
+              message: 'Expand the dropdown',
+              description:
+                'The ARIA label of the button to expand the mobile dropdown navbar item',
+            })
+          : translate({
+              id: 'theme.navbar.mobileDropdown.collapseButton.collapseAriaLabel',
+              message: 'Collapse the dropdown',
+              description:
+                'The ARIA label of the button to collapse the mobile dropdown navbar item',
+            })
+      }
+      aria-expanded={!collapsed}
+      type="button"
+      className="clean-btn menu__caret"
+      onClick={onClick}
+    />
+  );
+}
+function useItemCollapsible({active}) {
+  const {collapsed, toggleCollapsed, setCollapsed} = useCollapsible({
+    initialState: () => !active,
+  });
+  // Expand if any item active after a navigation
+  useEffect(() => {
+    if (active) {
+      setCollapsed(false);
+    }
+  }, [active, setCollapsed]);
+  return {
+    collapsed,
+    toggleCollapsed,
+  };
+}
+export default function DropdownNavbarItemMobile({
+  items,
+  className,
+  position, // Need to destructure position from props so that it doesn't get passed on.
+  onClick,
+  ...props
+}) {
+  const localPathname = useLocalPathname();
+  const isActive = isSamePath(props.to, localPathname);
+  const containsActive = containsActiveItems(items, localPathname);
+  const {collapsed, toggleCollapsed} = useItemCollapsible({
+    active: isActive || containsActive,
+  });
+  // # 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...
+  const href = props.to ? undefined : '#';
+  return (
+    <li
+      className={clsx('menu__list-item', {
+        'menu__list-item--collapsed': collapsed,
+      })}>
+      <div
+        className={clsx('menu__list-item-collapsible', {
+          'menu__list-item-collapsible--active': isActive,
+        })}>
+        <NavbarNavLink
+          role="button"
+          className={clsx(
+            styles.dropdownNavbarItemMobile,
+            'menu__link menu__link--sublist',
+            className,
+          )}
+          href={href}
+          {...props}
+          onClick={(e) => {
+            // Prevent navigation when link is "#"
+            if (href === '#') {
+              e.preventDefault();
+            }
+            // Otherwise we let navigation eventually happen, and/or collapse
+            toggleCollapsed();
+          }}>
+          {props.children ?? props.label}
+        </NavbarNavLink>
+        <CollapseButton
+          collapsed={collapsed}
+          onClick={(e) => {
+            e.preventDefault();
+            toggleCollapsed();
+          }}
+        />
+      </div>
+
+      <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>
+  );
+}

package/lib/theme/NavbarItem/DropdownNavbarItem/index.js

@@ -4,148 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, {useState, useRef, useEffect} 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 from '@theme/NavbarItem';
-import styles from './styles.module.css';
-function isItemActive(item, localPathname) {
-  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, localPathname) {
-  return items.some((item) => isItemActive(item, localPathname));
-}
-function DropdownNavbarItemDesktop({
-  items,
-  position,
-  className,
-  onClick,
-  ...props
-}) {
-  const dropdownRef = useRef(null);
-  const [showDropdown, setShowDropdown] = useState(false);
-  useEffect(() => {
-    const handleClickOutside = (event) => {
-      if (!dropdownRef.current || dropdownRef.current.contains(event.target)) {
-        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
-}) {
-  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 from 'react';
+import DropdownNavbarItemMobile from '@theme/NavbarItem/DropdownNavbarItem/Mobile';
+import DropdownNavbarItemDesktop from '@theme/NavbarItem/DropdownNavbarItem/Desktop';
 export default function DropdownNavbarItem({mobile = false, ...props}) {
   const Comp = mobile ? DropdownNavbarItemMobile : DropdownNavbarItemDesktop;
   return <Comp {...props} />;

package/lib/theme/Tag/index.js

@@ -11,6 +11,7 @@ import styles from './styles.module.css';
 export default function Tag({permalink, label, count, description}) {
   return (
     <Link
+      rel="tag"
       href={permalink}
       title={description}
       className={clsx(

package/lib/theme/ThemeProvider/TitleFormatter/index.d.ts

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

package/lib/theme/ThemeProvider/TitleFormatter/index.js

@@ -0,0 +1,19 @@
+/**
+ * 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 {TitleFormatterProvider} from '@docusaurus/theme-common/internal';
+const formatter = (params) => {
+  // Add your own title formatting logic here!
+  return params.defaultFormatter(params);
+};
+export default function ThemeProviderTitleFormatter({children}) {
+  return (
+    <TitleFormatterProvider formatter={formatter}>
+      {children}
+    </TitleFormatterProvider>
+  );
+}

package/lib/theme/ThemeProvider/index.d.ts

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

package/lib/theme/ThemeProvider/index.js

@@ -0,0 +1,11 @@
+/**
+ * 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 TitleFormatterProvider from '@theme/ThemeProvider/TitleFormatter';
+export default function ThemeProvider({children}) {
+  return <TitleFormatterProvider>{children}</TitleFormatterProvider>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "3.7.0",
+  "version": "3.8.0-canary-6324",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,19 +20,19 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "3.7.0",
-    "@docusaurus/logger": "3.7.0",
-    "@docusaurus/mdx-loader": "3.7.0",
-    "@docusaurus/module-type-aliases": "3.7.0",
-    "@docusaurus/plugin-content-blog": "3.7.0",
-    "@docusaurus/plugin-content-docs": "3.7.0",
-    "@docusaurus/plugin-content-pages": "3.7.0",
-    "@docusaurus/theme-common": "3.7.0",
-    "@docusaurus/theme-translations": "3.7.0",
-    "@docusaurus/types": "3.7.0",
-    "@docusaurus/utils": "3.7.0",
-    "@docusaurus/utils-common": "3.7.0",
-    "@docusaurus/utils-validation": "3.7.0",
+    "@docusaurus/core": "3.8.0-canary-6324",
+    "@docusaurus/logger": "3.8.0-canary-6324",
+    "@docusaurus/mdx-loader": "3.8.0-canary-6324",
+    "@docusaurus/module-type-aliases": "3.8.0-canary-6324",
+    "@docusaurus/plugin-content-blog": "3.8.0-canary-6324",
+    "@docusaurus/plugin-content-docs": "3.8.0-canary-6324",
+    "@docusaurus/plugin-content-pages": "3.8.0-canary-6324",
+    "@docusaurus/theme-common": "3.8.0-canary-6324",
+    "@docusaurus/theme-translations": "3.8.0-canary-6324",
+    "@docusaurus/types": "3.8.0-canary-6324",
+    "@docusaurus/utils": "3.8.0-canary-6324",
+    "@docusaurus/utils-common": "3.8.0-canary-6324",
+    "@docusaurus/utils-validation": "3.8.0-canary-6324",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "copy-text-to-clipboard": "^3.2.0",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "dd59750c16fe6908a26f18806a54d4c3dbe6db43"
+  "gitHead": "1fdcae691b9f171b90695b15e8e643eb031cb96a"
 }

package/src/getSwizzleConfig.ts

@@ -159,7 +159,7 @@ export default function getSwizzleConfig(): SwizzleConfig {
       'CodeBlock/Content': {
         actions: {
           eject: 'unsafe',
-          wrap: 'forbidden',
+          wrap: 'unsafe',
         },
         description:
           'The folder containing components responsible for rendering different types of CodeBlock content.',

package/src/index.ts

@@ -14,6 +14,7 @@ import {
   getAnnouncementBarInlineScript,
   DataAttributeQueryStringInlineJavaScript,
 } from './inlineScripts';
+import {SvgSpriteDefs} from './inlineSvgSprites';
 import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import type {Plugin as PostCssPlugin} from 'postcss';
@@ -121,6 +122,14 @@ export default function themeClassic(
     injectHtmlTags() {
       return {
         preBodyTags: [
+          {
+            tagName: 'svg',
+            attributes: {
+              xmlns: 'http://www.w3.org/2000/svg',
+              style: 'display: none;',
+            },
+            innerHTML: SvgSpriteDefs,
+          },
           {
             tagName: 'script',
             innerHTML: `

package/src/inlineScripts.ts

@@ -30,43 +30,22 @@ export function getThemeInlineScript({
   return `(function() {
     var defaultMode = '${defaultMode}';
     var respectPrefersColorScheme = ${respectPrefersColorScheme};
-
-    function setDataThemeAttribute(theme) {
-      document.documentElement.setAttribute('data-theme', theme);
+    function getSystemColorMode() {
+      return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
     }
-
     function getQueryStringTheme() {
       try {
         return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
-      } catch (e) {
-      }
+      } catch (e) {}
     }
-
     function getStoredTheme() {
       try {
         return window['${siteStorage.type}'].getItem('${themeStorageKey}');
-      } catch (err) {
-      }
+      } catch (err) {}
     }
-
     var initialTheme = getQueryStringTheme() || getStoredTheme();
-    if (initialTheme !== null) {
-      setDataThemeAttribute(initialTheme);
-    } else {
-      if (
-        respectPrefersColorScheme &&
-        window.matchMedia('(prefers-color-scheme: dark)').matches
-      ) {
-        setDataThemeAttribute('dark');
-      } else if (
-        respectPrefersColorScheme &&
-        window.matchMedia('(prefers-color-scheme: light)').matches
-      ) {
-        setDataThemeAttribute('light');
-      } else {
-        setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
-      }
-    }
+    document.documentElement.setAttribute('data-theme', initialTheme || (respectPrefersColorScheme ? getSystemColorMode() : defaultMode));
+    document.documentElement.setAttribute('data-theme-choice', initialTheme || (respectPrefersColorScheme ? 'system' : defaultMode));
   })();`;
 }
 

package/src/inlineSvgSprites.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+
+// For icons that are heavily repeated in the static html output
+// See also https://github.com/facebook/docusaurus/issues/5865
+export const SvgSpriteDefs = `<defs>
+<symbol id="theme-svg-external-link" viewBox="0 0 24 24"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z" /></symbol>
+</defs>`;

package/src/options.ts

@@ -7,6 +7,10 @@
 
 import {themes} from 'prism-react-renderer';
 import {Joi, URISchema} from '@docusaurus/utils-validation';
+import type {
+  PropVersionItem,
+  PropVersionItems,
+} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
 import type {Options, PluginOptions} from '@docusaurus/theme-classic';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import type {
@@ -210,6 +214,17 @@ const DocsVersionDropdownNavbarItemSchema = NavbarItemBaseSchema.append({
   dropdownActiveClassDisabled: Joi.boolean(),
   dropdownItemsBefore: Joi.array().items(DropdownSubitemSchema).default([]),
   dropdownItemsAfter: Joi.array().items(DropdownSubitemSchema).default([]),
+  versions: Joi.alternatives().try(
+    Joi.array().items(Joi.string().min(1)).min(1),
+    Joi.object<PropVersionItems>()
+      .pattern(
+        Joi.string().min(1),
+        Joi.object<PropVersionItem>({
+          label: Joi.string().min(1),
+        }),
+      )
+      .min(1),
+  ),
 });
 
 const LocaleDropdownNavbarItemSchema = NavbarItemBaseSchema.append({

package/src/theme/AnnouncementBar/index.tsx

@@ -6,7 +6,8 @@
  */
 
 import React, {type ReactNode} from 'react';
-import {useThemeConfig} from '@docusaurus/theme-common';
+import clsx from 'clsx';
+import {ThemeClassNames, useThemeConfig} from '@docusaurus/theme-common';
 import {useAnnouncementBar} from '@docusaurus/theme-common/internal';
 import AnnouncementBarCloseButton from '@theme/AnnouncementBar/CloseButton';
 import AnnouncementBarContent from '@theme/AnnouncementBar/Content';
@@ -22,7 +23,10 @@ export default function AnnouncementBar(): ReactNode {
   const {backgroundColor, textColor, isCloseable} = announcementBar!;
   return (
     <div
-      className={styles.announcementBar}
+      className={clsx(
+        ThemeClassNames.announcementBar.container,
+        styles.announcementBar,
+      )}
       style={{backgroundColor, color: textColor}}
       role="banner">
       {isCloseable && <div className={styles.announcementBarPlaceholder} />}

package/src/theme/CodeBlock/Buttons/Button/index.tsx

@@ -0,0 +1,19 @@
+/**
+ * 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 type {Props} from '@theme/CodeBlock/Buttons/Button';
+
+export default function CodeBlockButton({
+  className,
+  ...props
+}: Props): ReactNode {
+  return (
+    <button type="button" {...props} className={clsx('clean-btn', className)} />
+  );
+}

package/src/theme/CodeBlock/{CopyButton → Buttons/CopyButton}/index.tsx

@@ -15,16 +15,44 @@ import React, {
 import clsx from 'clsx';
 import copy from 'copy-text-to-clipboard';
 import {translate} from '@docusaurus/Translate';
-import type {Props} from '@theme/CodeBlock/CopyButton';
+import {useCodeBlockContext} from '@docusaurus/theme-common/internal';
+import Button from '@theme/CodeBlock/Buttons/Button';
+import type {Props} from '@theme/CodeBlock/Buttons/CopyButton';
 import IconCopy from '@theme/Icon/Copy';
 import IconSuccess from '@theme/Icon/Success';
 
 import styles from './styles.module.css';
 
-export default function CopyButton({code, className}: Props): ReactNode {
+function title() {
+  return translate({
+    id: 'theme.CodeBlock.copy',
+    message: 'Copy',
+    description: 'The copy button label on code blocks',
+  });
+}
+
+function ariaLabel(isCopied: boolean) {
+  return isCopied
+    ? translate({
+        id: 'theme.CodeBlock.copied',
+        message: 'Copied',
+        description: 'The copied button label on code blocks',
+      })
+    : translate({
+        id: 'theme.CodeBlock.copyButtonAriaLabel',
+        message: 'Copy code to clipboard',
+        description: 'The ARIA label for copy code blocks button',
+      });
+}
+
+function useCopyButton() {
+  const {
+    metadata: {code},
+  } = useCodeBlockContext();
   const [isCopied, setIsCopied] = useState(false);
   const copyTimeout = useRef<number | undefined>(undefined);
-  const handleCopyCode = useCallback(() => {
+
+  const copyCode = useCallback(() => {
     copy(code);
     setIsCopied(true);
     copyTimeout.current = window.setTimeout(() => {
@@ -34,38 +62,26 @@ export default function CopyButton({code, className}: Props): ReactNode {
 
   useEffect(() => () => window.clearTimeout(copyTimeout.current), []);
 
+  return {copyCode, isCopied};
+}
+
+export default function CopyButton({className}: Props): ReactNode {
+  const {copyCode, isCopied} = useCopyButton();
+
   return (
-    <button
-      type="button"
-      aria-label={
-        isCopied
-          ? translate({
-              id: 'theme.CodeBlock.copied',
-              message: 'Copied',
-              description: 'The copied button label on code blocks',
-            })
-          : translate({
-              id: 'theme.CodeBlock.copyButtonAriaLabel',
-              message: 'Copy code to clipboard',
-              description: 'The ARIA label for copy code blocks button',
-            })
-      }
-      title={translate({
-        id: 'theme.CodeBlock.copy',
-        message: 'Copy',
-        description: 'The copy button label on code blocks',
-      })}
+    <Button
+      aria-label={ariaLabel(isCopied)}
+      title={title()}
       className={clsx(
-        'clean-btn',
         className,
         styles.copyButton,
         isCopied && styles.copyButtonCopied,
       )}
-      onClick={handleCopyCode}>
+      onClick={copyCode}>
       <span className={styles.copyButtonIcons} aria-hidden="true">
         <IconCopy className={styles.copyButtonIcon} />
         <IconSuccess className={styles.copyButtonSuccessIcon} />
       </span>
-    </button>
+    </Button>
   );
 }