@docusaurus/theme-classic 2.0.0-beta.15 → 2.0.0-beta.16

package/lib-next/theme/SearchBar.js

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 // By default, the classic theme does not provide any SearchBar implementation
-// If you swizzled this file, it is your responsibility to provide an implementation
+// If you swizzled this, it is your responsibility to provide an implementation
 // Tip: swizzle the SearchBar from the Algolia theme for inspiration:
 // npm run swizzle @docusaurus/theme-search-algolia SearchBar
 export {default} from '@docusaurus/Noop';

package/lib-next/theme/SearchMetadata/index.js

@@ -6,15 +6,20 @@
  */
 import React from 'react';
 import Head from '@docusaurus/Head';
-// Note: we don't couple this to Algolia/DocSearch on purpose
-// We may want to support other search engine plugins too
-// Search plugins should swizzle/override this comp to add their behavior
+// Note: we bias toward using Algolia metadata on purpose
+// Not doing so leads to confusion in the community,
+// as it requires to first crawl the site with the Algolia plugin enabled first
+// - https://github.com/facebook/docusaurus/issues/6693
+// - https://github.com/facebook/docusaurus/issues/4555
 export default function SearchMetadata({locale, version, tag}) {
+  // Seems safe to consider here the locale is the language, as the existing
+  // docsearch:language filter is afaik a regular string-based filter
+  const language = locale;
   return (
     <Head>
-      {locale && <meta name="docusaurus_locale" content={locale} />}
-      {version && <meta name="docusaurus_version" content={version} />}
-      {tag && <meta name="docusaurus_tag" content={tag} />}
+      {language && <meta name="docsearch:language" content={language} />}
+      {version && <meta name="docsearch:version" content={version} />}
+      {tag && <meta name="docsearch:docusaurus_tag" content={tag} />}
     </Head>
   );
 }

package/lib-next/theme/SkipToContent/index.js

@@ -16,7 +16,7 @@ function programmaticFocus(el) {
   el.removeAttribute('tabindex');
 }
 
-function SkipToContent() {
+export default function SkipToContent() {
   const containerRef = useRef(null);
   const {action} = useHistory();
 
@@ -49,5 +49,3 @@ function SkipToContent() {
     </div>
   );
 }
-
-export default SkipToContent;

package/lib-next/theme/TOC/index.js

@@ -8,12 +8,11 @@ import React from 'react';
 import clsx from 'clsx';
 import TOCItems from '@theme/TOCItems';
 import styles from './styles.module.css'; // Using a custom className
-// This prevents TOC highlighting to highlight TOCInline/TOCCollapsible by mistake
+// This prevents TOCInline/TOCCollapsible getting highlighted by mistake
 
 const LINK_CLASS_NAME = 'table-of-contents__link toc-highlight';
 const LINK_ACTIVE_CLASS_NAME = 'table-of-contents__link--active';
-
-function TOC({className, ...props}) {
+export default function TOC({className, ...props}) {
   return (
     <div className={clsx(styles.tableOfContents, 'thin-scrollbar', className)}>
       <TOCItems
@@ -24,5 +23,3 @@ function TOC({className, ...props}) {
     </div>
   );
 }
-
-export default TOC;

package/lib-next/theme/TOCInline/index.js

@@ -7,8 +7,7 @@
 import React from 'react';
 import styles from './styles.module.css';
 import TOCItems from '@theme/TOCItems';
-
-function TOCInline({toc, minHeadingLevel, maxHeadingLevel}) {
+export default function TOCInline({toc, minHeadingLevel, maxHeadingLevel}) {
   return (
     <div className={styles.tableOfContentsInline}>
       <TOCItems
@@ -21,5 +20,3 @@ function TOCInline({toc, minHeadingLevel, maxHeadingLevel}) {
     </div>
   );
 }
-
-export default TOCInline;

package/lib-next/theme/TOCItems/index.js

@@ -7,8 +7,8 @@
 import React, {useMemo} from 'react';
 import {
   useThemeConfig,
-  useTOCFilter,
   useTOCHighlight,
+  useFilteredAndTreeifiedTOC,
 } from '@docusaurus/theme-common'; // Recursive component rendering the toc tree
 
 /* eslint-disable jsx-a11y/control-has-associated-label */
@@ -56,7 +56,7 @@ export default function TOCItems({
     minHeadingLevelOption ?? themeConfig.tableOfContents.minHeadingLevel;
   const maxHeadingLevel =
     maxHeadingLevelOption ?? themeConfig.tableOfContents.maxHeadingLevel;
-  const tocFiltered = useTOCFilter({
+  const tocTree = useFilteredAndTreeifiedTOC({
     toc,
     minHeadingLevel,
     maxHeadingLevel,
@@ -76,7 +76,7 @@ export default function TOCItems({
   useTOCHighlight(tocHighlightConfig);
   return (
     <TOCItemList
-      toc={tocFiltered}
+      toc={tocTree}
       className={className}
       linkClassName={linkClassName}
       {...props}

package/lib-next/theme/TabItem/index.js

@@ -5,8 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-
-function TabItem({children, hidden, className}) {
+export default function TabItem({children, hidden, className}) {
   return (
     <div
       role="tabpanel"
@@ -18,5 +17,3 @@ function TabItem({children, hidden, className}) {
     </div>
   );
 }
-
-export default TabItem;

package/lib-next/theme/Tabs/__tests__/index.test.js

@@ -133,7 +133,9 @@ describe('Tabs', () => {
               }))}
               defaultValue={0}>
               {tabs.map((t, idx) => (
-                <TabItem value={idx}>{t}</TabItem>
+                <TabItem key={idx} value={idx}>
+                  {t}
+                </TabItem>
               ))}
             </Tabs>
           </TabGroupChoiceProvider>

package/lib-next/theme/Tabs/index.js

@@ -42,7 +42,7 @@ function TabsComponent(props) {
     );
   });
   const values =
-    valuesProp ?? // We only pick keys that we recognize. MDX would inject some keys by default
+    valuesProp ?? // Only pick keys that we recognize. MDX would inject some keys by default
     children.map(({props: {value, label, attributes}}) => ({
       value,
       label,

package/lib-next/theme/Tag/index.js

@@ -8,8 +8,7 @@ import React from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import styles from './styles.module.css';
-
-function Tag(props) {
+export default function Tag(props) {
   const {permalink, name, count} = props;
   return (
     <Link
@@ -23,5 +22,3 @@ function Tag(props) {
     </Link>
   );
 }
-
-export default Tag;

package/lib-next/theme/TagsListByLetter/index.js

@@ -25,7 +25,7 @@ function TagLetterEntryItem({letterEntry}) {
   );
 }
 
-function TagsListByLetter({tags}) {
+export default function TagsListByLetter({tags}) {
   const letterList = listTagsByLetters(tags);
   return (
     <section className="margin-vert--lg">
@@ -38,5 +38,3 @@ function TagsListByLetter({tags}) {
     </section>
   );
 }
-
-export default TagsListByLetter;

package/lib-next/theme/ThemedImage/index.js

@@ -9,8 +9,7 @@ import clsx from 'clsx';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import {useColorMode} from '@docusaurus/theme-common';
 import styles from './styles.module.css';
-
-function ThemedImage(props) {
+export default function ThemedImage(props) {
   const isBrowser = useIsBrowser();
   const {isDarkTheme} = useColorMode();
   const {sources, className, alt = '', ...propsRest} = props;
@@ -37,5 +36,3 @@ function ThemedImage(props) {
     </>
   );
 }
-
-export default ThemedImage;

package/lib-next/theme/ThemedImage/styles.module.css

@@ -9,10 +9,10 @@
   display: none;
 }
 
-html[data-theme='light'] .themedImage--light {
+[data-theme='light'] .themedImage--light {
   display: initial;
 }
 
-html[data-theme='dark'] .themedImage--dark {
+[data-theme='dark'] .themedImage--dark {
   display: initial;
 }

package/lib-next/theme/Toggle/index.js

@@ -4,9 +4,10 @@
  * 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, memo} from 'react';
+import React, {useState, useRef, useEffect, memo} from 'react';
 import {useThemeConfig} from '@docusaurus/theme-common';
 import useIsBrowser from '@docusaurus/useIsBrowser';
+import {translate} from '@docusaurus/Translate';
 import clsx from 'clsx';
 import styles from './styles.module.css'; // Based on react-toggle (https://github.com/aaronshaf/react-toggle/).
 
@@ -16,6 +17,9 @@ const ToggleComponent = memo(
     const [checked, setChecked] = useState(defaultChecked);
     const [focused, setFocused] = useState(false);
     const inputRef = useRef(null);
+    useEffect(() => {
+      setChecked(defaultChecked);
+    }, [defaultChecked]);
     return (
       <div
         className={clsx(styles.toggle, className, {
@@ -47,7 +51,26 @@ const ToggleComponent = memo(
           checked={checked}
           type="checkbox"
           className={styles.toggleScreenReader}
-          aria-label="Switch between dark and light mode"
+          aria-label={translate(
+            {
+              message: 'Switch between dark and light mode (currently {mode})',
+              id: 'theme.colorToggle.ariaLabel',
+              description: 'The ARIA label for the navbar color mode toggle',
+            },
+            {
+              mode: checked
+                ? translate({
+                    message: 'dark mode',
+                    id: 'theme.colorToggle.ariaLabel.mode.dark',
+                    description: 'The name for the dark color mode',
+                  })
+                : translate({
+                    message: 'light mode',
+                    id: 'theme.colorToggle.ariaLabel.mode.light',
+                    description: 'The name for the light color mode',
+                  }),
+            },
+          )}
           onChange={onChange}
           onClick={() => setChecked(!checked)}
           onFocus={() => setFocused(true)}

package/lib-next/theme/prism-include-languages.js

@@ -4,28 +4,22 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import siteConfig from '@generated/docusaurus.config';
+export default function prismIncludeLanguages(PrismObject) {
+  const {
+    themeConfig: {prism},
+  } = siteConfig;
+  const {additionalLanguages} = prism; // Prism components work on the Prism instance on the window, while prism-
+  // react-renderer uses its own Prism instance. We temporarily mount the
+  // instance onto window, import components to enhance it, then remove it to
+  // avoid polluting global namespace.
+  // You can mutate PrismObject: registering plugins, deleting languages... As
+  // long as you don't re-assign it
 
-const prismIncludeLanguages = (PrismObject) => {
-  if (ExecutionEnvironment.canUseDOM) {
-    const {
-      themeConfig: {prism},
-    } = siteConfig;
-    const {additionalLanguages} = prism; // Prism components work on the Prism instance on the window, while
-    // prism-react-renderer uses its own Prism instance. We temporarily mount
-    // the instance onto window, import components to enhance it, then remove it
-    // to avoid polluting global namespace.
-    // You can mutate this object: registering plugins, deleting languages... As
-    // long as you don't re-assign it
-
-    window.Prism = PrismObject;
-    additionalLanguages.forEach((lang) => {
-      // eslint-disable-next-line global-require, import/no-dynamic-require
-      require(`prismjs/components/prism-${lang}`);
-    });
-    delete window.Prism;
-  }
-};
-
-export default prismIncludeLanguages;
+  globalThis.Prism = PrismObject;
+  additionalLanguages.forEach((lang) => {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    require(`prismjs/components/prism-${lang}`);
+  });
+  delete globalThis.Prism;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "2.0.0-beta.15",
+  "version": "2.0.0-beta.16",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -21,35 +21,34 @@
     "format:lib-next": "prettier --config ../../.prettierrc --write \"lib-next/**/*.{js,ts,jsx,tsc}\""
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.15",
-    "@docusaurus/plugin-content-blog": "2.0.0-beta.15",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.15",
-    "@docusaurus/plugin-content-pages": "2.0.0-beta.15",
-    "@docusaurus/theme-common": "2.0.0-beta.15",
-    "@docusaurus/theme-translations": "2.0.0-beta.15",
-    "@docusaurus/utils": "2.0.0-beta.15",
-    "@docusaurus/utils-common": "2.0.0-beta.15",
-    "@docusaurus/utils-validation": "2.0.0-beta.15",
-    "@mdx-js/react": "^1.6.21",
+    "@docusaurus/core": "2.0.0-beta.16",
+    "@docusaurus/plugin-content-blog": "2.0.0-beta.16",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.16",
+    "@docusaurus/plugin-content-pages": "2.0.0-beta.16",
+    "@docusaurus/theme-common": "2.0.0-beta.16",
+    "@docusaurus/theme-translations": "2.0.0-beta.16",
+    "@docusaurus/utils": "2.0.0-beta.16",
+    "@docusaurus/utils-common": "2.0.0-beta.16",
+    "@docusaurus/utils-validation": "2.0.0-beta.16",
+    "@mdx-js/react": "^1.6.22",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.0.1",
     "infima": "0.2.0-alpha.37",
-    "lodash": "^4.17.20",
-    "postcss": "^8.3.7",
+    "lodash": "^4.17.21",
+    "postcss": "^8.4.6",
     "prism-react-renderer": "^1.2.1",
-    "prismjs": "^1.23.0",
+    "prismjs": "^1.27.0",
     "react-router-dom": "^5.2.0",
     "rtlcss": "^3.3.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.15",
-    "@docusaurus/types": "2.0.0-beta.15",
-    "@types/mdx-js__react": "^1.5.4",
-    "@types/parse-numeric-range": "^0.0.1",
-    "@types/prismjs": "^1.16.2",
-    "@types/rtlcss": "^3.1.1",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.16",
+    "@docusaurus/types": "2.0.0-beta.16",
+    "@types/mdx-js__react": "^1.5.5",
+    "@types/prismjs": "^1.26.0",
+    "@types/rtlcss": "^3.1.2",
     "cross-env": "^7.0.3",
-    "fs-extra": "^10.0.0",
+    "fs-extra": "^10.0.1",
     "react-test-renderer": "^17.0.2",
     "utility-types": "^3.10.0"
   },
@@ -60,5 +59,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "6cfad16436c07d8d11e5c2e1486dc59afd483e33"
+  "gitHead": "eb43c4d4f95a4fb97dc9bb9dc615413e0dc2e1e7"
 }

package/src/getSwizzleConfig.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 {SwizzleConfig} from '@docusaurus/types';
+
+export default function getSwizzleConfig(): SwizzleConfig {
+  return {
+    components: {
+      CodeBlock: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description:
+          'The component used to render multi-line code blocks, generally used in Markdown files.',
+      },
+      DocSidebar: {
+        actions: {
+          wrap: 'safe',
+          eject: 'unsafe', // too much technical code in sidebar, not very safe atm
+        },
+        description: 'The sidebar component on docs pages',
+      },
+      Footer: {
+        actions: {
+          wrap: 'safe',
+          eject: 'unsafe', // TODO split footer into smaller parts
+        },
+        description: "The footer component of you site's layout",
+      },
+      NotFound: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description:
+          'The global 404 page of your site, meant to be ejected and customized',
+      },
+      SearchBar: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        // TODO how to describe this one properly?
+        // By default it's an empty placeholder for the user to fill
+        description:
+          'The search bar component of your site, appearing in the navbar.',
+      },
+      IconArrow: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description: 'The arrow icon component',
+      },
+      IconEdit: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description: 'The edit icon component',
+      },
+      IconMenu: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description: 'The menu icon component',
+      },
+
+      'prism-include-languages': {
+        actions: {
+          wrap: 'forbidden', // not a component!
+          eject: 'safe',
+        },
+        description:
+          'The Prism languages to include for code block syntax highlighting. Meant to be ejected.',
+      },
+      MDXComponents: {
+        actions: {
+          wrap: 'forbidden', /// TODO allow wrapping objects???
+          eject: 'safe',
+        },
+        description:
+          'The MDX components to use for rendering MDX files. Meant to be ejected.',
+      },
+
+      // TODO should probably not even appear here
+      'NavbarItem/utils': {
+        actions: {
+          wrap: 'forbidden',
+          eject: 'forbidden',
+        },
+      },
+    },
+  };
+}

package/src/index.ts

@@ -23,7 +23,7 @@ const ContextReplacementPlugin: typeof webpack.ContextReplacementPlugin =
   requireFromDocusaurusCore('webpack/lib/ContextReplacementPlugin');
 
 // Need to be inlined to prevent dark mode FOUC
-// Make sure that the 'storageKey' is the same as the one in `/theme/hooks/useTheme.js`
+// Make sure the key is the same as the one in `/theme/hooks/useTheme.js`
 const ThemeStorageKey = 'theme';
 const noFlashColorMode = ({
   defaultMode,
@@ -64,15 +64,17 @@ const noFlashColorMode = ({
   }
 })();`;
 
-// Duplicated constant. Unfortunately we can't import it from theme-common, as we need to support older nodejs versions without ESM support
+// Duplicated constant. Unfortunately we can't import it from theme-common, as
+// we need to support older nodejs versions without ESM support
 // TODO: import from theme-common once we only support Node.js with ESM support
 // + move all those announcementBar stuff there too
 export const AnnouncementBarDismissStorageKey =
   'docusaurus.announcement.dismiss';
 const AnnouncementBarDismissDataAttribute =
   'data-announcement-bar-initially-dismissed';
-// We always render the announcement bar html on the server, to prevent layout shifts on React hydration
-// The theme can use CSS + the data attribute to hide the announcement bar asap (before React hydration)
+// We always render the announcement bar html on the server, to prevent layout
+// shifts on React hydration. The theme can use CSS + the data attribute to hide
+// the announcement bar asap (before React hydration)
 const AnnouncementBarInlineJavaScript = `
 (function() {
   function isDismissed() {
@@ -205,21 +207,5 @@ ${announcementBar ? AnnouncementBarInlineJavaScript : ''}
   };
 }
 
-const swizzleAllowedComponents = [
-  'CodeBlock',
-  'DocSidebar',
-  'Footer',
-  'NotFound',
-  'SearchBar',
-  'IconArrow',
-  'IconEdit',
-  'IconMenu',
-  'hooks/useTheme',
-  'prism-include-languages',
-];
-
-export function getSwizzleComponentList(): string[] {
-  return swizzleAllowedComponents;
-}
-
+export {default as getSwizzleConfig} from './getSwizzleConfig';
 export {validateThemeConfig} from './validateThemeConfig';

package/src/theme/AnnouncementBar/index.tsx

@@ -13,7 +13,7 @@ import IconClose from '@theme/IconClose';
 
 import styles from './styles.module.css';
 
-function AnnouncementBar(): JSX.Element | null {
+export default function AnnouncementBar(): JSX.Element | null {
   const {isActive, close} = useAnnouncementBar();
   const {announcementBar} = useThemeConfig();
 
@@ -51,5 +51,3 @@ function AnnouncementBar(): JSX.Element | null {
     </div>
   );
 }
-
-export default AnnouncementBar;

package/src/theme/BackToTopButton/index.tsx

@@ -22,7 +22,9 @@ const threshold = 300;
 // TODO proper detection is currently unreliable!
 // see https://github.com/wessberg/scroll-behavior-polyfill/issues/16
 const SupportsNativeSmoothScrolling = false;
-// const SupportsNativeSmoothScrolling = ExecutionEnvironment.canUseDOM && 'scrollBehavior' in document.documentElement.style;
+// const SupportsNativeSmoothScrolling =
+//   ExecutionEnvironment.canUseDOM &&
+//   'scrollBehavior' in document.documentElement.style;
 
 type CancelScrollTop = () => void;
 
@@ -44,13 +46,14 @@ function smoothScrollTopPolyfill(): CancelScrollTop {
   }
   rafRecursion();
 
-  // Break the recursion
-  // Prevents the user from "fighting" against that recursion producing a weird UX
+  // Break the recursion. Prevents the user from "fighting" against that
+  // recursion producing a weird UX
   return () => raf && cancelAnimationFrame(raf);
 }
 
 type UseSmoothScrollTopReturn = {
-  // We use a cancel function because the non-native smooth scroll-top implementation must be interrupted if user scroll down
+  // We use a cancel function because the non-native smooth scroll-top
+  // implementation must be interrupted if user scroll down
   smoothScrollTop: () => void;
   cancelScrollToTop: CancelScrollTop;
 };
@@ -70,7 +73,7 @@ function useSmoothScrollToTop(): UseSmoothScrollTopReturn {
   };
 }
 
-function BackToTopButton(): JSX.Element {
+export default function BackToTopButton(): JSX.Element {
   const [show, setShow] = useState(false);
   const isFocusedAnchor = useRef(false);
   const {smoothScrollTop, cancelScrollToTop} = useSmoothScrollToTop();
@@ -138,5 +141,3 @@ function BackToTopButton(): JSX.Element {
     />
   );
 }
-
-export default BackToTopButton;

package/src/theme/BackToTopButton/styles.module.css

@@ -13,12 +13,13 @@
   background-color: var(--ifm-color-emphasis-200);
   width: 3rem;
   height: 3rem;
-  z-index: var(--ifm-z-index-fixed);
+  z-index: calc(var(--ifm-z-index-fixed) - 1);
   box-shadow: var(--ifm-global-shadow-lw);
   transition: all var(--ifm-transition-fast)
     var(--ifm-transition-timing-default);
   opacity: 0;
   transform: scale(0);
+  visibility: hidden;
 }
 
 .backToTopButton::after {
@@ -39,4 +40,5 @@
 .backToTopButtonShow {
   opacity: 1;
   transform: scale(1);
+  visibility: visible;
 }

package/src/theme/BlogLayout/index.tsx

@@ -12,7 +12,7 @@ import BlogSidebar from '@theme/BlogSidebar';
 
 import type {Props} from '@theme/BlogLayout';
 
-function BlogLayout(props: Props): JSX.Element {
+export default function BlogLayout(props: Props): JSX.Element {
   const {sidebar, toc, children, ...layoutProps} = props;
   const hasSidebar = sidebar && sidebar.items.length > 0;
 
@@ -40,5 +40,3 @@ function BlogLayout(props: Props): JSX.Element {
     </Layout>
   );
 }
-
-export default BlogLayout;

package/src/theme/BlogListPage/index.tsx

@@ -14,7 +14,7 @@ import BlogListPaginator from '@theme/BlogListPaginator';
 import type {Props} from '@theme/BlogListPage';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 
-function BlogListPage(props: Props): JSX.Element {
+export default function BlogListPage(props: Props): JSX.Element {
   const {metadata, items, sidebar} = props;
   const {
     siteConfig: {title: siteTitle},
@@ -48,5 +48,3 @@ function BlogListPage(props: Props): JSX.Element {
     </BlogLayout>
   );
 }
-
-export default BlogListPage;