@docusaurus/theme-common 2.0.0-beta.16 → 2.0.0-beta.19

package/src/utils/tocUtils.ts

@@ -6,7 +6,7 @@
  */
 
 import {useMemo} from 'react';
-import type {TOCItem} from '@docusaurus/types';
+import type {TOCItem} from '@docusaurus/mdx-loader';
 
 export type TOCTreeNode = {
   readonly value: string;
@@ -30,11 +30,11 @@ function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
   const prevIndexForLevel = Array(7).fill(-1);
 
   headings.forEach((curr, currIndex) => {
-    // take the last seen index for each ancestor level. the highest
-    // index will be the direct ancestor of the current heading.
+    // Take the last seen index for each ancestor level. the highest index will
+    // be the direct ancestor of the current heading.
     const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
     curr.parentIndex = Math.max(...ancestorLevelIndexes);
-    // mark that curr.level was last seen at the current index
+    // Mark that curr.level was last seen at the current index.
     prevIndexForLevel[curr.level] = currIndex;
   });
 
@@ -44,7 +44,7 @@ function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
   headings.forEach((heading) => {
     const {parentIndex, ...rest} = heading;
     if (parentIndex >= 0) {
-      headings[parentIndex].children.push(rest);
+      headings[parentIndex]!.children.push(rest);
     } else {
       rootNodes.push(rest);
     }
@@ -52,6 +52,10 @@ function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
   return rootNodes;
 }
 
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect. Memoized for performance.
+ */
 export function useTreeifiedTOC(toc: TOCItem[]): readonly TOCTreeNode[] {
   return useMemo(() => treeifyTOC(toc), [toc]);
 }
@@ -87,6 +91,18 @@ function filterTOC({
   });
 }
 
+/**
+ * Takes a flat TOC list (from the MDX loader) and treeifies it into what the
+ * TOC components expect, applying the `minHeadingLevel` and `maxHeadingLevel`.
+ * Memoized for performance.
+ *
+ * **Important**: this is not the same as `useTreeifiedTOC(toc.filter(...))`,
+ * because we have to filter the TOC after it has been treeified. This is mostly
+ * to ensure that weird TOC structures preserve their semantics. For example, an
+ * h3-h2-h4 sequence should not be treeified as an "h3 > h4" hierarchy with
+ * min=3, max=4, but should rather be "[h3, h4]" (since the h2 heading has split
+ * the two headings and they are not parent-children)
+ */
 export function useFilteredAndTreeifiedTOC({
   toc,
   minHeadingLevel,
@@ -97,12 +113,7 @@ export function useFilteredAndTreeifiedTOC({
   maxHeadingLevel: number;
 }): readonly TOCTreeNode[] {
   return useMemo(
-    () =>
-      // Note: we have to filter the TOC after it has been treeified. This is
-      // mostly to ensure that weird TOC structures preserve their semantics.
-      // For example, an h3-h2-h4 sequence should not be treeified as an h3 > h4
-      // hierarchy with min=3, max=4, but should rather be [h3, h4]
-      filterTOC({toc: treeifyTOC(toc), minHeadingLevel, maxHeadingLevel}),
+    () => filterTOC({toc: treeifyTOC(toc), minHeadingLevel, maxHeadingLevel}),
     [toc, minHeadingLevel, maxHeadingLevel],
   );
 }

package/src/utils/useAlternatePageUtils.ts

@@ -8,12 +8,26 @@
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useLocation} from '@docusaurus/router';
 
-// Permits to obtain the url of the current page in another locale
-// Useful to generate hreflang meta headers etc...
-// See https://developers.google.com/search/docs/advanced/crawling/localized-versions
+/**
+ * Permits to obtain the url of the current page in another locale, useful to
+ * generate hreflang meta headers etc...
+ *
+ * @see https://developers.google.com/search/docs/advanced/crawling/localized-versions
+ */
 export function useAlternatePageUtils(): {
+  /**
+   * Everything (pathname, base URL, etc.) is read from the context. Just tell
+   * it which locale to link to and it will give you the alternate link for the
+   * current page.
+   */
   createUrl: ({
+    /** The locale name to link to. */
     locale,
+    /**
+     * For hreflang SEO headers, we need it to be fully qualified (full
+     * protocol/domain/path...); but for locale dropdowns, using a pathname is
+     * good enough.
+     */
     fullyQualified,
   }: {
     locale: string;
@@ -46,8 +60,6 @@ export function useAlternatePageUtils(): {
     fullyQualified,
   }: {
     locale: string;
-    // For hreflang SEO headers, we need it to be fully qualified (full
-    // protocol/domain/path...) or locale dropdown, using a path is good enough
     fullyQualified: boolean;
   }) {
     return `${fullyQualified ? url : ''}${getLocalizedBaseUrl(

package/src/utils/useLocalPathname.ts

@@ -5,12 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useLocation} from '@docusaurus/router';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 
-// Get the pathname of current route, without the optional site baseUrl
-// - /docs/myDoc => /docs/myDoc
-// - /baseUrl/docs/myDoc => /docs/myDoc
+/**
+ * Get the pathname of current route, without the optional site baseUrl.
+ * - `/docs/myDoc` => `/docs/myDoc`
+ * - `/baseUrl/docs/myDoc` => `/docs/myDoc`
+ */
 export function useLocalPathname(): string {
   const {
     siteConfig: {baseUrl},

package/src/utils/useLocationChange.ts

@@ -8,17 +8,19 @@
 import {useEffect} from 'react';
 import {useLocation} from '@docusaurus/router';
 import type {Location} from 'history';
-import {usePrevious} from './usePrevious';
-import {useDynamicCallback} from './reactUtils';
+import {useDynamicCallback, usePrevious} from './reactUtils';
 
-type LocationChangeEvent = {
-  location: Location;
-  previousLocation: Location | undefined;
-};
-
-type OnLocationChange = (locationChangeEvent: LocationChangeEvent) => void;
-
-export function useLocationChange(onLocationChange: OnLocationChange): void {
+/**
+ * Fires an effect when the location changes (which includes hash, query, etc.).
+ * Importantly, doesn't fire when there's no previous location: see
+ * https://github.com/facebook/docusaurus/pull/6696
+ */
+export function useLocationChange(
+  onLocationChange: (locationChangeEvent: {
+    location: Location;
+    previousLocation: Location | undefined;
+  }) => void,
+): void {
   const location = useLocation();
   const previousLocation = usePrevious(location);
 

package/src/utils/usePluralForm.ts

@@ -50,17 +50,17 @@ function createLocalePluralForms(locale: string): LocalePluralForms {
 }
 
 /**
- * Poor man's PluralSelector implementation, using an english fallback. We want
- * a lightweight, future-proof and good-enough solution. We don't want a perfect
- * and heavy solution.
+ * Poor man's `PluralSelector` implementation, using an English fallback. We
+ * want a lightweight, future-proof and good-enough solution. We don't want a
+ * perfect and heavy solution.
  *
  * Docusaurus classic theme has only 2 deeply nested labels requiring complex
- * plural rules. We don't want to use Intl + PluralRules polyfills + full ICU
- * syntax (react-intl) just for that.
+ * plural rules. We don't want to use `Intl` + `PluralRules` polyfills + full
+ * ICU syntax (react-intl) just for that.
  *
  * Notes:
- * - 2021: 92+% Browsers support Intl.PluralRules, and support will increase in
- * the future
+ * - 2021: 92+% Browsers support `Intl.PluralRules`, and support will increase
+ * in the future
  * - NodeJS >= 13 has full ICU support by default
  * - In case of "mismatch" between SSR and Browser ICU support, React keeps
  * working!
@@ -70,21 +70,13 @@ function useLocalePluralForms(): LocalePluralForms {
     i18n: {currentLocale},
   } = useDocusaurusContext();
   return useMemo(() => {
-    // @ts-expect-error checking Intl.PluralRules in case browser doesn't
-    // have it (e.g Safari 12-)
-    if (Intl.PluralRules) {
-      try {
-        return createLocalePluralForms(currentLocale);
-      } catch {
-        console.error(`Failed to use Intl.PluralRules for locale "${currentLocale}".
-Docusaurus will fallback to a default/fallback (English) Intl.PluralRules implementation.
+    try {
+      return createLocalePluralForms(currentLocale);
+    } catch (err) {
+      console.error(`Failed to use Intl.PluralRules for locale "${currentLocale}".
+Docusaurus will fallback to the default (English) implementation.
+Error: ${(err as Error).message}
 `);
-        return EnglishPluralForms;
-      }
-    } else {
-      console.error(`Intl.PluralRules not available!
-Docusaurus will fallback to a default/fallback (English) Intl.PluralRules implementation.
-        `);
       return EnglishPluralForms;
     }
   }, [currentLocale]);
@@ -99,21 +91,32 @@ function selectPluralMessage(
   const parts = pluralMessages.split(separator);
 
   if (parts.length === 1) {
-    return parts[0];
+    return parts[0]!;
   }
   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} plural forms: ${pluralMessages} `,
+      `For locale=${localePluralForms.locale}, a maximum of ${localePluralForms.pluralForms.length} plural forms are expected (${localePluralForms.pluralForms}), but the message contains ${parts.length}: ${pluralMessages}`,
     );
   }
   const pluralForm = localePluralForms.select(count);
   const pluralFormIndex = localePluralForms.pluralForms.indexOf(pluralForm);
   // In case of not enough plural form messages, we take the last one (other)
   // instead of returning undefined
-  return parts[Math.min(pluralFormIndex, parts.length - 1)];
+  return parts[Math.min(pluralFormIndex, parts.length - 1)]!;
 }
 
+/**
+ * Reads the current locale and returns an interface very similar to
+ * `Intl.PluralRules`.
+ */
 export function usePluralForm(): {
+  /**
+   * Give it a `count` and it will select the relevant message from
+   * `pluralMessages`. `pluralMessages` should be separated by `|`, and in the
+   * order of "zero", "one", "two", "few", "many", "other". The actual selection
+   * is done by `Intl.PluralRules`, which tells us all plurals the locale has
+   * and which plural we should use for `count`.
+   */
   selectMessage: (count: number, pluralMessages: string) => string;
 } {
   const localePluralForm = useLocalePluralForms();

package/src/utils/useThemeConfig.ts

@@ -7,8 +7,8 @@
 
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import type {PrismTheme} from 'prism-react-renderer';
-import type {CSSProperties} from 'react';
 import type {DeepPartial} from 'utility-types';
+import type {MagicCommentConfig} from './codeBlockUtils';
 
 export type DocsVersionPersistence = 'localStorage' | 'none';
 
@@ -18,7 +18,7 @@ export type NavbarItem = {
   items?: NavbarItem[];
   label?: string;
   position?: 'left' | 'right';
-} & Record<string, unknown>;
+} & {[key: string]: unknown};
 
 export type NavbarLogo = {
   src: string;
@@ -43,12 +43,6 @@ export type ColorModeConfig = {
   defaultMode: 'light' | 'dark';
   disableSwitch: boolean;
   respectPrefersColorScheme: boolean;
-  switchConfig: {
-    darkIcon: string;
-    darkIconStyle: CSSProperties;
-    lightIcon: string;
-    lightIconStyle: CSSProperties;
-  };
 };
 
 export type AnnouncementBarConfig = {
@@ -60,10 +54,11 @@ export type AnnouncementBarConfig = {
 };
 
 export type PrismConfig = {
-  theme?: PrismTheme;
+  theme: PrismTheme;
   darkTheme?: PrismTheme;
   defaultLanguage?: string;
-  additionalLanguages?: string[];
+  additionalLanguages: string[];
+  magicComments: MagicCommentConfig[];
 };
 
 export type FooterLinkItem = {
@@ -72,18 +67,20 @@ export type FooterLinkItem = {
   href?: string;
   html?: string;
   prependBaseUrlToHref?: string;
+} & {[key: string]: unknown};
+
+export type FooterLogo = {
+  alt?: string;
+  src: string;
+  srcDark?: string;
+  width?: string | number;
+  height?: string | number;
+  href?: string;
 };
 
 export type FooterBase = {
   style: 'light' | 'dark';
-  logo?: {
-    alt?: string;
-    src?: string;
-    srcDark?: string;
-    width?: string | number;
-    height?: string | number;
-    href?: string;
-  };
+  logo?: FooterLogo;
   copyright?: string;
 };
 
@@ -109,6 +106,10 @@ export type TableOfContents = {
 export type ThemeConfig = {
   docs: {
     versionPersistence: DocsVersionPersistence;
+    sidebar: {
+      hideable: boolean;
+      autoCollapseCategories: boolean;
+    };
   };
 
   // TODO we should complete this theme config type over time
@@ -121,17 +122,17 @@ export type ThemeConfig = {
   announcementBar?: AnnouncementBarConfig;
   prism: PrismConfig;
   footer?: Footer;
-  hideableSidebar: boolean;
-  autoCollapseSidebarCategories: boolean;
   image?: string;
-  metadata: Array<Record<string, string>>;
-  sidebarCollapsible: boolean;
+  metadata: Array<{[key: string]: string}>;
   tableOfContents: TableOfContents;
 };
 
 // User-provided theme config, unnormalized
 export type UserThemeConfig = DeepPartial<ThemeConfig>;
 
+/**
+ * A convenient/more semantic way to get theme config from context.
+ */
 export function useThemeConfig(): ThemeConfig {
   return useDocusaurusContext().siteConfig.themeConfig as ThemeConfig;
 }