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

package/src/theme/NavbarItem/DocSidebarNavbarItem.tsx

@@ -0,0 +1,84 @@
+/**
+ * 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 DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
+import {
+  useLatestVersion,
+  useActiveDocContext,
+} from '@docusaurus/plugin-content-docs/client';
+import clsx from 'clsx';
+import {getInfimaActiveClassName} from '@theme/NavbarItem/utils';
+import {useDocsPreferredVersion, uniq} from '@docusaurus/theme-common';
+
+import type {Props} from '@theme/NavbarItem/DocSidebarNavbarItem';
+import type {
+  GlobalVersion,
+  GlobalSidebar,
+} from '@docusaurus/plugin-content-docs/client';
+
+function getSidebarLink(versions: GlobalVersion[], sidebarId: string) {
+  const allSidebars = versions
+    .flatMap((version) => {
+      if (version.sidebars) {
+        return Object.entries(version.sidebars);
+      }
+      return undefined;
+    })
+    .filter(
+      (sidebarItem): sidebarItem is [string, GlobalSidebar] => !!sidebarItem,
+    );
+  const sidebarEntry = allSidebars.find((sidebar) => sidebar[0] === sidebarId);
+  if (!sidebarEntry) {
+    throw new Error(
+      `DocSidebarNavbarItem: couldn't find any sidebar with id "${sidebarId}" in version${
+        versions.length ? 's' : ''
+      } ${versions.map((version) => version.name).join(', ')}".
+Available sidebar ids are:
+- ${Object.keys(allSidebars).join('\n- ')}`,
+    );
+  }
+  if (!sidebarEntry[1].link) {
+    throw new Error(
+      `DocSidebarNavbarItem: couldn't find any document for sidebar with id "${sidebarId}"`,
+    );
+  }
+  return sidebarEntry[1].link;
+}
+
+export default function DocSidebarNavbarItem({
+  sidebarId,
+  label,
+  docsPluginId,
+  ...props
+}: Props): JSX.Element {
+  const {activeVersion, activeDoc} = useActiveDocContext(docsPluginId);
+  const {preferredVersion} = useDocsPreferredVersion(docsPluginId);
+  const latestVersion = useLatestVersion(docsPluginId);
+
+  // Versions used to look for the doc to link to, ordered + no duplicate
+  const versions = uniq(
+    [activeVersion, preferredVersion, latestVersion].filter(
+      Boolean,
+    ) as GlobalVersion[],
+  );
+  const sidebarLink = getSidebarLink(versions, sidebarId);
+  const activeDocInfimaClassName = getInfimaActiveClassName(props.mobile);
+
+  return (
+    <DefaultNavbarItem
+      exact
+      {...props}
+      className={clsx(props.className, {
+        [activeDocInfimaClassName]: activeDoc?.sidebar === sidebarId,
+      })}
+      activeClassName={activeDocInfimaClassName}
+      label={label ?? sidebarLink.label}
+      to={sidebarLink.path}
+    />
+  );
+}

package/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx

@@ -12,13 +12,14 @@ import {
   useVersions,
   useLatestVersion,
   useActiveDocContext,
-} from '@theme/hooks/useDocs';
+} from '@docusaurus/plugin-content-docs/client';
 import type {Props} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
 import {useDocsPreferredVersion} from '@docusaurus/theme-common';
 import {translate} from '@docusaurus/Translate';
-import type {GlobalDataVersion} from '@docusaurus/plugin-content-docs';
+import type {GlobalVersion} from '@docusaurus/plugin-content-docs/client';
+import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 
-const getVersionMainDoc = (version: GlobalDataVersion) =>
+const getVersionMainDoc = (version: GlobalVersion) =>
   version.docs.find((doc) => doc.id === version.mainDocId)!;
 
 export default function DocsVersionDropdownNavbarItem({
@@ -36,7 +37,7 @@ export default function DocsVersionDropdownNavbarItem({
   const {preferredVersion, savePreferredVersionName} =
     useDocsPreferredVersion(docsPluginId);
 
-  function getItems() {
+  function getItems(): LinkLikeNavbarItemProps[] {
     const versionLinks = versions.map((version) => {
       // We try to link to the same doc, in another version
       // When not possible, fallback to the "main doc" of the version
@@ -64,7 +65,7 @@ export default function DocsVersionDropdownNavbarItem({
 
   // Mobile dropdown is handled a bit differently
   const dropdownLabel =
-    mobile && items
+    mobile && items.length > 1
       ? translate({
           id: 'theme.navbar.mobileVersionsDropdown.label',
           message: 'Versions',
@@ -73,7 +74,9 @@ export default function DocsVersionDropdownNavbarItem({
         })
       : dropdownVersion.label;
   const dropdownTo =
-    mobile && items ? undefined : getVersionMainDoc(dropdownVersion).path;
+    mobile && items.length > 1
+      ? undefined
+      : getVersionMainDoc(dropdownVersion).path;
 
   // We don't want to render a version dropdown with 0 or 1 item
   // If we build the site with a single docs version (onlyIncludeVersions: ['1.0.0'])

package/src/theme/NavbarItem/DocsVersionNavbarItem.tsx

@@ -10,8 +10,8 @@ import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import {
   useActiveVersion,
   useLatestVersion,
-  GlobalVersion,
-} from '@theme/hooks/useDocs';
+  type GlobalVersion,
+} from '@docusaurus/plugin-content-docs/client';
 import type {Props} from '@theme/NavbarItem/DocsVersionNavbarItem';
 import {useDocsPreferredVersion} from '@docusaurus/theme-common';
 

package/src/theme/NavbarItem/DropdownNavbarItem.tsx

@@ -20,7 +20,7 @@ import type {
 } from '@theme/NavbarItem/DropdownNavbarItem';
 import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 
-import {NavLink} from '@theme/NavbarItem/DefaultNavbarItem';
+import NavbarNavLink from '@theme/NavbarItem/NavbarNavLink';
 import NavbarItem from '@theme/NavbarItem';
 
 const dropdownLinkActiveClass = 'dropdown__link--active';
@@ -55,7 +55,6 @@ function DropdownNavbarItemDesktop({
   ...props
 }: DesktopOrMobileNavBarItemProps) {
   const dropdownRef = useRef<HTMLDivElement>(null);
-  const dropdownMenuRef = useRef<HTMLUListElement>(null);
   const [showDropdown, setShowDropdown] = useState(false);
 
   useEffect(() => {
@@ -85,7 +84,7 @@ function DropdownNavbarItemDesktop({
         'dropdown--right': position === 'right',
         'dropdown--show': showDropdown,
       })}>
-      <NavLink
+      <NavbarNavLink
         href={props.to ? undefined : '#'}
         className={clsx('navbar__link', className)}
         {...props}
@@ -97,8 +96,8 @@ function DropdownNavbarItemDesktop({
           }
         }}>
         {props.children ?? props.label}
-      </NavLink>
-      <ul ref={dropdownMenuRef} className="dropdown__menu">
+      </NavbarNavLink>
+      <ul className="dropdown__menu">
         {items.map((childItemProps, i) => (
           <NavbarItem
             isDropdownItem
@@ -147,7 +146,7 @@ function DropdownNavbarItemMobile({
       className={clsx('menu__list-item', {
         'menu__list-item--collapsed': collapsed,
       })}>
-      <NavLink
+      <NavbarNavLink
         role="button"
         className={clsx('menu__link menu__link--sublist', className)}
         {...props}
@@ -156,7 +155,7 @@ function DropdownNavbarItemMobile({
           toggleCollapsed();
         }}>
         {props.children ?? props.label}
-      </NavLink>
+      </NavbarNavLink>
       <Collapsible lazy as="ul" className="menu__list" collapsed={collapsed}>
         {items.map((childItemProps, i) => (
           <NavbarItem

package/src/theme/NavbarItem/NavbarNavLink.tsx

@@ -0,0 +1,68 @@
+/**
+ * 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 Link from '@docusaurus/Link';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import type {Props} from '@theme/NavbarItem/NavbarNavLink';
+import IconExternalLink from '@theme/IconExternalLink';
+import isInternalUrl from '@docusaurus/isInternalUrl';
+import {isRegexpStringMatch} from '@docusaurus/theme-common';
+
+const dropdownLinkActiveClass = 'dropdown__link--active';
+
+export default function NavbarNavLink({
+  activeBasePath,
+  activeBaseRegex,
+  to,
+  href,
+  label,
+  activeClassName = '',
+  prependBaseUrlToHref,
+  ...props
+}: Props): JSX.Element {
+  // TODO all this seems hacky
+  // {to: 'version'} should probably be forbidden, in favor of {to: '/version'}
+  const toUrl = useBaseUrl(to);
+  const activeBaseUrl = useBaseUrl(activeBasePath);
+  const normalizedHref = useBaseUrl(href, {forcePrependBaseUrl: true});
+  const isExternalLink = label && href && !isInternalUrl(href);
+  const isDropdownLink = activeClassName === dropdownLinkActiveClass;
+
+  return (
+    <Link
+      {...(href
+        ? {
+            href: prependBaseUrlToHref ? normalizedHref : href,
+          }
+        : {
+            isNavLink: true,
+            activeClassName: !props.className?.includes(activeClassName)
+              ? activeClassName
+              : '',
+            to: toUrl,
+            ...(activeBasePath || activeBaseRegex
+              ? {
+                  isActive: (_match, location) =>
+                    activeBaseRegex
+                      ? isRegexpStringMatch(activeBaseRegex, location.pathname)
+                      : location.pathname.startsWith(activeBaseUrl),
+                }
+              : null),
+          })}
+      {...props}>
+      {isExternalLink ? (
+        <span>
+          {label}
+          <IconExternalLink {...(isDropdownLink && {width: 12, height: 12})} />
+        </span>
+      ) : (
+        label
+      )}
+    </Link>
+  );
+}

package/src/theme/NavbarItem/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import DropdownNavbarItem, {
-  Props as DropdownNavbarItemProps,
+  type Props as DropdownNavbarItemProps,
 } from '@theme/NavbarItem/DropdownNavbarItem';
 import LocaleDropdownNavbarItem from '@theme/NavbarItem/LocaleDropdownNavbarItem';
 import SearchNavbarItem from '@theme/NavbarItem/SearchNavbarItem';
@@ -16,7 +16,7 @@ import type {Types, Props} from '@theme/NavbarItem';
 
 const NavbarItemComponents: Record<
   Exclude<Types, undefined>,
-  // TODO: properly type this
+  // Not really worth typing, as we pass all props down immediately
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   () => (props: any) => JSX.Element
 > = {
@@ -32,6 +32,7 @@ const NavbarItemComponents: Record<
   docsVersionDropdown: () =>
     require('@theme/NavbarItem/DocsVersionDropdownNavbarItem').default,
   doc: () => require('@theme/NavbarItem/DocNavbarItem').default,
+  docSidebar: () => require('@theme/NavbarItem/DocSidebarNavbarItem').default,
   /* eslint-enable @typescript-eslint/no-var-requires, global-require */
 } as const;
 
@@ -57,9 +58,6 @@ function getComponentType(
   return type as NavbarItemComponentType;
 }
 
-export const getInfimaActiveClassName = (mobile?: boolean): string =>
-  mobile ? 'menu__link--active' : 'navbar__link--active';
-
 export default function NavbarItem({type, ...props}: Props): JSX.Element {
   const componentType = getComponentType(
     type,

package/{lib-next/theme/hooks/styles.css → src/theme/NavbarItem/utils.ts}

@@ -5,6 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-body:not(.navigation-with-keyboard) *:not(input):focus {
-  outline: none;
-}
+// eslint-disable-next-line import/no-named-export
+export const getInfimaActiveClassName = (mobile?: boolean): string =>
+  mobile ? 'menu__link--active' : 'navbar__link--active';

package/src/theme/PaginatorNavLink/index.tsx

@@ -0,0 +1,22 @@
+/**
+ * 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 Link from '@docusaurus/Link';
+import type {Props} from '@theme/PaginatorNavLink';
+
+function PaginatorNavLink(props: Props): JSX.Element {
+  const {permalink, title, subLabel} = props;
+  return (
+    <Link className="pagination-nav__link" to={permalink}>
+      {subLabel && <div className="pagination-nav__sublabel">{subLabel}</div>}
+      <div className="pagination-nav__label">{title}</div>
+    </Link>
+  );
+}
+
+export default PaginatorNavLink;

package/src/theme/SkipToContent/index.tsx

@@ -40,7 +40,7 @@ function SkipToContent(): JSX.Element {
   });
 
   return (
-    <div ref={containerRef}>
+    <div ref={containerRef} role="region">
       {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
       <a href="#" className={styles.skipToContent} onClick={handleSkip}>
         <Translate

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

@@ -1,3 +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.
+ */
+
 .skipToContent {
   position: fixed;
   top: 1rem;

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

@@ -20,7 +20,7 @@
   width: 100%;
 }
 
-.tocCollapsibleButton:after {
+.tocCollapsibleButton::after {
   content: '';
   background: var(--ifm-menu-link-sublist-icon) 50% 50% / 2rem 2rem no-repeat;
   filter: var(--ifm-menu-link-sublist-icon-filter);
@@ -45,6 +45,6 @@
   display: block;
 }
 
-.tocCollapsibleExpanded .tocCollapsibleButton:after {
+.tocCollapsibleExpanded .tocCollapsibleButton::after {
   transform: none;
 }

package/src/theme/TOCItems/index.tsx

@@ -7,9 +7,9 @@
 
 import React, {useMemo} from 'react';
 import type {TOCItemsProps} from '@theme/TOCItems';
-import {TOCItem} from '@docusaurus/types';
+import type {TOCItem} from '@docusaurus/types';
 import {
-  TOCHighlightConfig,
+  type TOCHighlightConfig,
   useThemeConfig,
   useTOCFilter,
   useTOCHighlight,

package/src/theme/Tabs/index.tsx

@@ -10,11 +10,14 @@ import React, {
   cloneElement,
   Children,
   isValidElement,
-  ReactElement,
+  type ReactElement,
 } from 'react';
 import useIsBrowser from '@docusaurus/useIsBrowser';
-import useUserPreferencesContext from '@theme/hooks/useUserPreferencesContext';
-import {useScrollPositionBlocker, duplicates} from '@docusaurus/theme-common';
+import {
+  useScrollPositionBlocker,
+  duplicates,
+  useTabGroupChoice,
+} from '@docusaurus/theme-common';
 import type {Props} from '@theme/Tabs';
 import type {Props as TabItemProps} from '@theme/TabItem';
 
@@ -51,7 +54,13 @@ function TabsComponent(props: Props): JSX.Element {
     );
   });
   const values =
-    valuesProp ?? children.map(({props: {value, label}}) => ({value, label}));
+    valuesProp ??
+    // We only pick keys that we recognize. MDX would inject some keys by default
+    children.map(({props: {value, label, attributes}}) => ({
+      value,
+      label,
+      attributes,
+    }));
   const dup = duplicates(values, (a, b) => a.value === b.value);
   if (dup.length > 0) {
     throw new Error(
@@ -77,7 +86,7 @@ function TabsComponent(props: Props): JSX.Element {
     );
   }
 
-  const {tabGroupChoices, setTabGroupChoices} = useUserPreferencesContext();
+  const {tabGroupChoices, setTabGroupChoices} = useTabGroupChoice();
   const [selectedValue, setSelectedValue] = useState(defaultValue);
   const tabRefs: (HTMLLIElement | null)[] = [];
   const {blockElementScrollPositionUntilNextRender} =
@@ -144,19 +153,25 @@ function TabsComponent(props: Props): JSX.Element {
           },
           className,
         )}>
-        {values.map(({value, label}) => (
+        {values.map(({value, label, attributes}) => (
           <li
             role="tab"
             tabIndex={selectedValue === value ? 0 : -1}
             aria-selected={selectedValue === value}
-            className={clsx('tabs__item', styles.tabItem, {
-              'tabs__item--active': selectedValue === value,
-            })}
             key={value}
             ref={(tabControl) => tabRefs.push(tabControl)}
             onKeyDown={handleKeydown}
             onFocus={handleTabChange}
-            onClick={handleTabChange}>
+            onClick={handleTabChange}
+            {...attributes}
+            className={clsx(
+              'tabs__item',
+              styles.tabItem,
+              attributes?.className as string,
+              {
+                'tabs__item--active': selectedValue === value,
+              },
+            )}>
             {label ?? value}
           </li>
         ))}

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

@@ -33,8 +33,8 @@
   border-left: 0;
 }
 
-.tagWithCount:before,
-.tagWithCount:after {
+.tagWithCount::before,
+.tagWithCount::after {
   content: '';
   position: absolute;
   top: 50%;
@@ -42,7 +42,7 @@
   transition: inherit;
 }
 
-.tagWithCount:before {
+.tagWithCount::before {
   right: 100%;
   transform: translate(50%, -50%) rotate(-45deg);
   width: 1.18rem;
@@ -51,7 +51,7 @@
   border-bottom: 0;
 }
 
-.tagWithCount:after {
+.tagWithCount::after {
   left: 0;
   transform: translateY(-50%);
   width: 0.5rem;

package/src/theme/TagsListByLetter/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 import Tag from '@theme/Tag';
 import type {Props} from '@theme/TagsListByLetter';
-import {listTagsByLetters, TagLetterEntry} from '@docusaurus/theme-common';
+import {listTagsByLetters, type TagLetterEntry} from '@docusaurus/theme-common';
 
 import styles from './styles.module.css';
 

package/src/theme/ThemedImage/index.tsx

@@ -9,14 +9,14 @@ import React from 'react';
 import clsx from 'clsx';
 
 import useIsBrowser from '@docusaurus/useIsBrowser';
-import useThemeContext from '@theme/hooks/useThemeContext';
+import {useColorMode} from '@docusaurus/theme-common';
 import type {Props} from '@theme/ThemedImage';
 
 import styles from './styles.module.css';
 
 function ThemedImage(props: Props): JSX.Element {
   const isBrowser = useIsBrowser();
-  const {isDarkTheme} = useThemeContext();
+  const {isDarkTheme} = useColorMode();
   const {sources, className, alt = '', ...propsRest} = props;
 
   type SourceName = keyof Props['sources'];

package/src/theme/Toggle/index.tsx

@@ -7,7 +7,7 @@
 
 import React, {useState, useRef, memo} from 'react';
 import type {Props} from '@theme/Toggle';
-import {useThemeConfig, ColorModeConfig} from '@docusaurus/theme-common';
+import {useThemeConfig, type ColorModeConfig} from '@docusaurus/theme-common';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 
 import clsx from 'clsx';

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

@@ -39,16 +39,16 @@
   position: absolute;
   width: 14px;
   height: 10px;
-  top: 0px;
-  bottom: 0px;
+  top: 0;
+  bottom: 0;
   margin: auto 0;
   left: 8px;
   opacity: 0;
   transition: opacity 0.25s ease;
 }
 
-[data-theme='dark'] .toggle .toggleTrackCheck,
-.toggleChecked .toggleTrackCheck {
+.toggleChecked .toggleTrackCheck,
+[data-theme='dark'] .toggle .toggleTrackCheck {
   opacity: 1;
   transition: opacity 0.25s ease;
 }
@@ -57,16 +57,16 @@
   position: absolute;
   width: 10px;
   height: 10px;
-  top: 0px;
-  bottom: 0px;
+  top: 0;
+  bottom: 0;
   margin: auto 0;
   right: 10px;
   opacity: 1;
   transition: opacity 0.25s ease;
 }
 
-[data-theme='dark'] .toggle .toggleTrackX,
-.toggleChecked .toggleTrackX {
+.toggleChecked .toggleTrackX,
+[data-theme='dark'] .toggle .toggleTrackX {
   opacity: 0;
 }
 
@@ -82,18 +82,19 @@
   transition: all 0.25s ease;
 }
 
-[data-theme='dark'] .toggle .toggleTrackThumb,
-.toggleChecked .toggleTrackThumb {
-  left: 27px;
-}
-
 .toggleFocused .toggleTrackThumb,
 .toggle:hover .toggleTrackThumb {
-  box-shadow: 0px 0px 2px 3px var(--ifm-color-primary);
+  box-shadow: 0 0 2px 3px var(--ifm-color-primary);
+}
+
+/* stylelint-disable-next-line no-descending-specificity */
+.toggleChecked .toggleTrackThumb,
+[data-theme='dark'] .toggle .toggleTrackThumb {
+  left: 27px;
 }
 
 .toggle:active:not(.toggleDisabled) .toggleTrackThumb {
-  box-shadow: 0px 0px 5px 5px var(--ifm-color-primary);
+  box-shadow: 0 0 5px 5px var(--ifm-color-primary);
 }
 
 .toggleIcon {

package/src/theme/prism-include-languages.ts

@@ -12,14 +12,21 @@ import type * as PrismNamespace from 'prismjs';
 const prismIncludeLanguages = (PrismObject: typeof PrismNamespace): void => {
   if (ExecutionEnvironment.canUseDOM) {
     const {
-      themeConfig: {prism = {}},
+      themeConfig: {prism},
     } = siteConfig;
-    const {additionalLanguages = []} = prism as {additionalLanguages: string[]};
+    const {additionalLanguages} = prism as {additionalLanguages: string[]};
 
+    // 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) => {
-      require(`prismjs/components/prism-${lang}`); // eslint-disable-line
+      // eslint-disable-next-line global-require, import/no-dynamic-require
+      require(`prismjs/components/prism-${lang}`);
     });
 
     delete (window as Window & {Prism?: typeof PrismNamespace}).Prism;