@docusaurus/theme-common 2.0.0-beta.20 → 2.0.0-beta.21

package/src/components/Collapsible/index.tsx

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import React, {
   useState,
   useEffect,
@@ -17,6 +16,7 @@ import React, {
   type SetStateAction,
   type ReactNode,
 } from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 
 const DefaultAnimationEasing = 'ease-in-out';
 
@@ -27,7 +27,7 @@ export function useCollapsible({
   initialState,
 }: {
   /** The initial state. Will be non-collapsed by default. */
-  initialState: boolean | (() => boolean);
+  initialState?: boolean | (() => boolean);
 }): {
   collapsed: boolean;
   setCollapsed: Dispatch<SetStateAction<boolean>>;
@@ -196,9 +196,7 @@ function CollapsibleBase({
   className,
   disableSSRStyle,
 }: CollapsibleBaseProps) {
-  // any because TS is a pain for HTML element refs, see https://twitter.com/sebastienlorber/status/1412784677795110914
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const collapsibleRef = useRef<any>(null);
+  const collapsibleRef = useRef<HTMLElement>(null);
 
   useCollapseAnimation({collapsibleRef, collapsed, animation});
 
@@ -206,7 +204,7 @@ function CollapsibleBase({
     <As
       // @ts-expect-error: the "too complicated type" is produced from
       // "CollapsibleElementType" being a huge union
-      ref={collapsibleRef}
+      ref={collapsibleRef as RefObject<never>} // Refs are contravariant, which is not expressible in TS
       style={disableSSRStyle ? undefined : getSSRStyle(collapsed)}
       onTransitionEnd={(e: React.TransitionEvent) => {
         if (e.propertyName !== 'height') {

package/src/components/Details/index.tsx

@@ -11,8 +11,8 @@ import React, {
   type ComponentProps,
   type ReactElement,
 } from 'react';
-import useIsBrowser from '@docusaurus/useIsBrowser';
 import clsx from 'clsx';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import {useCollapsible, Collapsible} from '../Collapsible';
 import styles from './styles.module.css';
 
@@ -92,7 +92,7 @@ export function Details({
         }
       }}>
       {/* eslint-disable-next-line @docusaurus/no-untranslated-text */}
-      {summary || <summary>Details</summary>}
+      {summary ?? <summary>Details</summary>}
 
       <Collapsible
         lazy={false} // Content might matter for SEO in this case

package/src/contexts/colorMode.tsx

@@ -14,9 +14,8 @@ import React, {
   useRef,
   type ReactNode,
 } from 'react';
-import {ReactContextError} from '../utils/reactUtils';
-
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import {ReactContextError} from '../utils/reactUtils';
 import {createStorageSlot} from '../utils/storageUtils';
 import {useThemeConfig} from '../utils/useThemeConfig';
 

package/src/contexts/docsPreferredVersion.tsx

@@ -13,22 +13,20 @@ import React, {
   useCallback,
   type ReactNode,
 } from 'react';
-import {
-  useThemeConfig,
-  type DocsVersionPersistence,
-} from '../utils/useThemeConfig';
-import {isDocsPluginEnabled} from '../utils/docsUtils';
-import {ReactContextError} from '../utils/reactUtils';
-import {createStorageSlot} from '../utils/storageUtils';
-
 import {
   useAllDocsData,
   useDocsData,
   type GlobalPluginData,
   type GlobalVersion,
 } from '@docusaurus/plugin-content-docs/client';
-
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
+import {
+  useThemeConfig,
+  type DocsVersionPersistence,
+} from '../utils/useThemeConfig';
+import {isDocsPluginEnabled} from '../utils/docsUtils';
+import {ReactContextError} from '../utils/reactUtils';
+import {createStorageSlot} from '../utils/storageUtils';
 
 const storageKey = (pluginId: string) => `docs-preferred-version-${pluginId}`;
 

package/src/contexts/docsSidebar.tsx

@@ -6,8 +6,8 @@
  */
 
 import React, {useMemo, useContext, type ReactNode} from 'react';
-import type {PropSidebar} from '@docusaurus/plugin-content-docs';
 import {ReactContextError} from '../utils/reactUtils';
+import type {PropSidebar} from '@docusaurus/plugin-content-docs';
 
 // Using a Symbol because null is a valid context value (a doc with no sidebar)
 // Inspired by https://github.com/jamiebuilds/unstated-next/blob/master/src/unstated-next.tsx

package/src/contexts/docsVersion.tsx

@@ -6,8 +6,8 @@
  */
 
 import React, {type ReactNode, useContext} from 'react';
-import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
 import {ReactContextError} from '../utils/reactUtils';
+import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
 
 const Context = React.createContext<PropVersionMetadata | null>(null);
 

package/src/hooks/usePrismTheme.ts

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {PrismTheme} from 'prism-react-renderer';
 import {useColorMode} from '../contexts/colorMode';
 import {useThemeConfig} from '../utils/useThemeConfig';
+import type {PrismTheme} from 'prism-react-renderer';
 
 /**
  * Returns a color-mode-dependent Prism theme: whatever the user specified in

package/src/hooks/useSearchPage.ts

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {useCallback, useEffect, useState} from 'react';
 import {useHistory} from '@docusaurus/router';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {useCallback, useEffect, useState} from 'react';
 
 const SEARCH_PARAM_QUERY = 'q';
 

package/src/hooks/useSkipToContent.ts

@@ -40,7 +40,7 @@ export function useSkipToContent(): {
     e.preventDefault();
 
     const targetElement: HTMLElement | null =
-      document.querySelector('main:first-of-type') ||
+      document.querySelector('main:first-of-type') ??
       document.querySelector(`.${ThemeClassNames.wrapper.main}`);
 
     if (targetElement) {

package/src/hooks/useTOCHighlight.ts

@@ -38,15 +38,12 @@ function getAnchors({
 }: {
   minHeadingLevel: number;
   maxHeadingLevel: number;
-}) {
+}): HTMLElement[] {
   const selectors = [];
   for (let i = minHeadingLevel; i <= maxHeadingLevel; i += 1) {
     selectors.push(`h${i}.anchor`);
   }
-
-  return Array.from(
-    document.querySelectorAll(selectors.join()),
-  ) as HTMLElement[];
+  return Array.from(document.querySelectorAll(selectors.join()));
 }
 
 function getActiveAnchor(
@@ -154,7 +151,7 @@ export function useTOCHighlight(config: TOCHighlightConfig | undefined): void {
     function updateLinkActiveClass(link: HTMLAnchorElement, active: boolean) {
       if (active) {
         if (lastActiveLinkRef.current && lastActiveLinkRef.current !== link) {
-          lastActiveLinkRef.current?.classList.remove(linkActiveClassName);
+          lastActiveLinkRef.current.classList.remove(linkActiveClassName);
         }
         link.classList.add(linkActiveClassName);
         lastActiveLinkRef.current = link;

package/src/utils/codeBlockUtils.ts

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import type {CSSProperties} from 'react';
 import rangeParser from 'parse-numeric-range';
 import type {PrismTheme} from 'prism-react-renderer';
-import type {CSSProperties} from 'react';
 
 const codeBlockTitleRegex = /title=(?<quote>["'])(?<title>.*?)\1/;
 const metastringLinesRangeRegex = /\{(?<range>[\d,-]+)\}/;
@@ -97,7 +97,7 @@ export function parseCodeBlockTitle(metastring?: string): string {
 }
 
 export function containsLineNumbers(metastring?: string): boolean {
-  return metastring?.includes('showLineNumbers') || false;
+  return Boolean(metastring?.includes('showLineNumbers'));
 }
 
 /**
@@ -171,7 +171,7 @@ export function parseLines(
     const metastringRangeClassName = magicComments[0]!.className;
     const lines = rangeParser(linesRange)
       .filter((n) => n > 0)
-      .map((n) => [n - 1, [metastringRangeClassName]]);
+      .map((n) => [n - 1, [metastringRangeClassName]] as [number, string[]]);
     return {lineClassNames: Object.fromEntries(lines), code};
   }
   if (language === undefined) {
@@ -189,7 +189,7 @@ export function parseLines(
   const lineToClassName: {[comment: string]: string} = Object.fromEntries(
     magicComments
       .filter((d) => d.line)
-      .map(({className, line}) => [line, className]),
+      .map(({className, line}) => [line!, className] as [string, string]),
   );
   const blockStartToClassName: {[comment: string]: string} = Object.fromEntries(
     magicComments
@@ -209,7 +209,9 @@ export function parseLines(
       lineNumber += 1;
       continue;
     }
-    const directive = match.slice(1).find((item) => item !== undefined)!;
+    const directive = match
+      .slice(1)
+      .find((item: string | undefined) => item !== undefined)!;
     if (lineToClassName[directive]) {
       blocks[lineToClassName[directive]!]!.range += `${lineNumber},`;
     } else if (blockStartToClassName[directive]) {

package/src/utils/docsUtils.tsx

@@ -6,6 +6,8 @@
  */
 
 import {useMemo} from 'react';
+import {matchPath, useLocation} from '@docusaurus/router';
+import renderRoutes from '@docusaurus/renderRoutes';
 import {
   useAllDocsData,
   useActivePlugin,
@@ -15,6 +17,12 @@ import {
   type GlobalSidebar,
   type GlobalDoc,
 } from '@docusaurus/plugin-content-docs/client';
+import type {Props as DocPageProps} from '@theme/DocPage';
+import {useDocsPreferredVersion} from '../contexts/docsPreferredVersion';
+import {useDocsVersion} from '../contexts/docsVersion';
+import {useDocsSidebar} from '../contexts/docsSidebar';
+import {uniq} from './jsUtils';
+import {isSamePath} from './routesUtils';
 import type {
   PropSidebar,
   PropSidebarItem,
@@ -22,14 +30,6 @@ import type {
   PropVersionDoc,
   PropSidebarBreadcrumbsItem,
 } from '@docusaurus/plugin-content-docs';
-import type {Props as DocPageProps} from '@theme/DocPage';
-import {useDocsPreferredVersion} from '../contexts/docsPreferredVersion';
-import {useDocsVersion} from '../contexts/docsVersion';
-import {useDocsSidebar} from '../contexts/docsSidebar';
-import {uniq} from './jsUtils';
-import {isSamePath} from './routesUtils';
-import {matchPath, useLocation} from '@docusaurus/router';
-import renderRoutes from '@docusaurus/renderRoutes';
 
 // TODO not ideal, see also "useDocs"
 export const isDocsPluginEnabled: boolean = !!useAllDocsData;
@@ -318,7 +318,7 @@ export function useDocRouteMetadata({
   }
 
   // For now, the sidebarName is added as route config: not ideal!
-  const sidebarName = currentDocRoute.sidebar;
+  const sidebarName = currentDocRoute.sidebar as string;
 
   const sidebarItems = sidebarName
     ? versionMetadata.docsSidebars[sidebarName]

package/src/utils/metadataUtils.tsx

@@ -6,8 +6,8 @@
  */
 
 import React, {type ReactNode} from 'react';
-import Head from '@docusaurus/Head';
 import clsx from 'clsx';
+import Head from '@docusaurus/Head';
 import useRouteContext from '@docusaurus/useRouteContext';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
 import {useTitleFormatter} from './generalUtils';

package/src/utils/reactUtils.tsx

@@ -70,7 +70,7 @@ export class ReactContextError extends Error {
     this.name = 'ReactContextError';
     this.message = `Hook ${
       this.stack?.split('\n')[1]?.match(/at (?:\w+\.)?(?<name>\w+)/)?.groups!
-        .name
-    } is called outside the <${providerName}>. ${additionalInfo || ''}`;
+        .name ?? ''
+    } is called outside the <${providerName}>. ${additionalInfo ?? ''}`;
   }
 }

package/src/utils/routesUtils.ts

@@ -18,7 +18,7 @@ export function isSamePath(
   path2: string | undefined,
 ): boolean {
   const normalize = (pathname: string | undefined) =>
-    (!pathname || pathname?.endsWith('/')
+    (!pathname || pathname.endsWith('/')
       ? pathname
       : `${pathname}/`
     )?.toLowerCase();

package/src/utils/scrollUtils.tsx

@@ -14,9 +14,9 @@ import React, {
   useRef,
   type ReactNode,
 } from 'react';
-import {useDynamicCallback, ReactContextError} from './reactUtils';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import useIsBrowser from '@docusaurus/useIsBrowser';
+import {useDynamicCallback, ReactContextError} from './reactUtils';
 
 type ScrollController = {
   /** A boolean ref tracking whether scroll events are enabled. */
@@ -112,11 +112,7 @@ export function useScrollPosition(
         return;
       }
       const currentPosition = getScrollPosition()!;
-
-      if (dynamicEffect) {
-        dynamicEffect(currentPosition, lastPositionRef.current);
-      }
-
+      dynamicEffect(currentPosition, lastPositionRef.current);
       lastPositionRef.current = currentPosition;
     };
 

package/src/utils/searchUtils.ts

@@ -9,8 +9,8 @@ import {
   useAllDocsData,
   useActivePluginAndVersion,
 } from '@docusaurus/plugin-content-docs/client';
-import {useDocsPreferredVersionByPluginId} from '../contexts/docsPreferredVersion';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import {useDocsPreferredVersionByPluginId} from '../contexts/docsPreferredVersion';
 
 export const DEFAULT_SEARCH_TAG = 'default';
 
@@ -39,7 +39,7 @@ export function useContextualSearchFilters(): {locale: string; tags: string[]} {
   // plugin instances.
   function getDocPluginTags(pluginId: string) {
     const activeVersion =
-      activePluginAndVersion?.activePlugin?.pluginId === pluginId
+      activePluginAndVersion?.activePlugin.pluginId === pluginId
         ? activePluginAndVersion.activeVersion
         : undefined;
 

package/src/utils/tocUtils.ts

@@ -27,7 +27,7 @@ function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
   // level <i>. We will modify these indices as we iterate through all headings.
   // e.g. if an ### H3 was last seen at index 2, then prevIndexForLevel[3] === 2
   // indices 0 and 1 will remain unused.
-  const prevIndexForLevel = Array(7).fill(-1);
+  const prevIndexForLevel = Array<number>(7).fill(-1);
 
   headings.forEach((curr, currIndex) => {
     // Take the last seen index for each ancestor level. the highest index will

package/src/utils/useLocationChange.ts

@@ -7,8 +7,8 @@
 
 import {useEffect} from 'react';
 import {useLocation} from '@docusaurus/router';
-import type {Location} from 'history';
 import {useDynamicCallback, usePrevious} from './reactUtils';
+import type {Location} from 'history';
 
 /**
  * Fires an effect when the location changes (which includes hash, query, etc.).

package/src/utils/usePluralForm.ts

@@ -95,7 +95,11 @@ function selectPluralMessage(
   }
   if (parts.length > localePluralForms.pluralForms.length) {
     console.error(
-      `For locale=${localePluralForms.locale}, a maximum of ${localePluralForms.pluralForms.length} plural forms are expected (${localePluralForms.pluralForms}), but the message contains ${parts.length}: ${pluralMessages}`,
+      `For locale=${localePluralForms.locale}, a maximum of ${
+        localePluralForms.pluralForms.length
+      } plural forms are expected (${localePluralForms.pluralForms.join(
+        ',',
+      )}), but the message contains ${parts.length}: ${pluralMessages}`,
     );
   }
   const pluralForm = localePluralForms.select(count);

package/src/utils/useThemeConfig.ts

@@ -32,7 +32,7 @@ export type NavbarLogo = {
 
 // TODO improve
 export type Navbar = {
-  style: 'dark' | 'primary';
+  style?: 'dark' | 'primary';
   hideOnScroll: boolean;
   title?: string;
   items: NavbarItem[];
@@ -85,10 +85,10 @@ export type FooterBase = {
 };
 
 export type MultiColumnFooter = FooterBase & {
-  links: Array<{
+  links: {
     title: string | null;
     items: FooterLinkItem[];
-  }>;
+  }[];
 };
 
 export type SimpleFooter = FooterBase & {
@@ -123,7 +123,7 @@ export type ThemeConfig = {
   prism: PrismConfig;
   footer?: Footer;
   image?: string;
-  metadata: Array<{[key: string]: string}>;
+  metadata: {[key: string]: string}[];
   tableOfContents: TableOfContents;
 };