@docusaurus/theme-common 2.0.0-beta.fc64c12e4 → 2.0.0

package/src/utils/storageUtils.ts

@@ -11,8 +11,12 @@ export type StorageType = typeof StorageTypes[number];
 
 const DefaultStorageType: StorageType = 'localStorage';
 
-// Will return null browser storage is unavailable (like running Docusaurus in iframe)
-// See https://github.com/facebook/docusaurus/pull/4501
+/**
+ * Will return `null` if browser storage is unavailable (like running Docusaurus
+ * in an iframe). This should NOT be called in SSR.
+ *
+ * @see https://github.com/facebook/docusaurus/pull/4501
+ */
 function getBrowserStorage(
   storageType: StorageType = DefaultStorageType,
 ): Storage | null {
@@ -23,21 +27,21 @@ function getBrowserStorage(
   }
   if (storageType === 'none') {
     return null;
-  } else {
-    try {
-      return window[storageType];
-    } catch (e) {
-      logOnceBrowserStorageNotAvailableWarning(e);
-      return null;
-    }
+  }
+  try {
+    return window[storageType];
+  } catch (err) {
+    logOnceBrowserStorageNotAvailableWarning(err as Error);
+    return null;
   }
 }
 
+let hasLoggedBrowserStorageNotAvailableWarning = false;
 /**
- * Poor man's memoization to avoid logging multiple times the same warning
- * Sometimes, localStorage/sessionStorage is unavailable due to browser policies
+ * Poor man's memoization to avoid logging multiple times the same warning.
+ * Sometimes, `localStorage`/`sessionStorage` is unavailable due to browser
+ * policies.
  */
-let hasLoggedBrowserStorageNotAvailableWarning = false;
 function logOnceBrowserStorageNotAvailableWarning(error: Error) {
   if (!hasLoggedBrowserStorageNotAvailableWarning) {
     console.warn(
@@ -50,11 +54,11 @@ Possible reasons: running Docusaurus in an iframe, in an incognito browser sessi
 }
 
 // Convenient storage interface for a single storage key
-export interface StorageSlot {
+export type StorageSlot = {
   get: () => string | null;
   set: (value: string) => void;
   del: () => void;
-}
+};
 
 const NoopStorageSlot: StorageSlot = {
   get: () => null,
@@ -62,7 +66,7 @@ const NoopStorageSlot: StorageSlot = {
   del: () => {},
 };
 
-//  Fail-fast, as storage APIs should not be used during the SSR process
+// Fail-fast, as storage APIs should not be used during the SSR process
 function createServerStorageSlot(key: string): StorageSlot {
   function throwError(): never {
     throw new Error(`Illegal storage API usage for storage key "${key}".
@@ -78,12 +82,19 @@ Please only call storage APIs in effects and event handlers.`);
 }
 
 /**
- * Creates an object for accessing a particular key in localStorage.
+ * Creates an interface to work on a particular key in the storage model.
+ * Note that this function only initializes the interface, but doesn't allocate
+ * anything by itself (i.e. no side-effects).
+ *
+ * The API is fail-safe, since usage of browser storage should be considered
+ * unreliable. Local storage might simply be unavailable (iframe + browser
+ * security) or operations might fail individually. Please assume that using
+ * this API can be a no-op. See also https://github.com/facebook/docusaurus/issues/6036
  */
-export const createStorageSlot = (
+export function createStorageSlot(
   key: string,
   options?: {persistence?: StorageType},
-): StorageSlot => {
+): StorageSlot {
   if (typeof window === 'undefined') {
     return createServerStorageSlot(key);
   }
@@ -92,14 +103,36 @@ export const createStorageSlot = (
     return NoopStorageSlot;
   }
   return {
-    get: () => browserStorage.getItem(key),
-    set: (value) => browserStorage.setItem(key, value),
-    del: () => browserStorage.removeItem(key),
+    get: () => {
+      try {
+        return browserStorage.getItem(key);
+      } catch (err) {
+        console.error(`Docusaurus storage error, can't get key=${key}`, err);
+        return null;
+      }
+    },
+    set: (value) => {
+      try {
+        browserStorage.setItem(key, value);
+      } catch (err) {
+        console.error(
+          `Docusaurus storage error, can't set ${key}=${value}`,
+          err,
+        );
+      }
+    },
+    del: () => {
+      try {
+        browserStorage.removeItem(key);
+      } catch (err) {
+        console.error(`Docusaurus storage error, can't delete key=${key}`, err);
+      }
+    },
   };
-};
+}
 
 /**
- * Returns a list of all the keys currently stored in browser storage
+ * Returns a list of all the keys currently stored in browser storage,
  * or an empty list if browser storage can't be accessed.
  */
 export function listStorageKeys(

package/src/utils/tagsUtils.ts

@@ -0,0 +1,50 @@
+/**
+ * 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 {translate} from '@docusaurus/Translate';
+import type {TagsListItem} from '@docusaurus/utils';
+
+export const translateTagsPageTitle = (): string =>
+  translate({
+    id: 'theme.tags.tagsPageTitle',
+    message: 'Tags',
+    description: 'The title of the tag list page',
+  });
+
+export type TagLetterEntry = {letter: string; tags: TagsListItem[]};
+
+function getTagLetter(tag: string): string {
+  return tag[0]!.toUpperCase();
+}
+
+/**
+ * Takes a list of tags (as provided by the content plugins), and groups them by
+ * their initials.
+ */
+export function listTagsByLetters(
+  tags: readonly TagsListItem[],
+): TagLetterEntry[] {
+  const groups: {[initial: string]: TagsListItem[]} = {};
+  Object.values(tags).forEach((tag) => {
+    const initial = getTagLetter(tag.label);
+    groups[initial] ??= [];
+    groups[initial]!.push(tag);
+  });
+
+  return (
+    Object.entries(groups)
+      // Sort letters
+      .sort(([letter1], [letter2]) => letter1.localeCompare(letter2))
+      .map(([letter, letterTags]) => {
+        // Sort tags inside a letter
+        const sortedTags = letterTags.sort((tag1, tag2) =>
+          tag1.label.localeCompare(tag2.label),
+        );
+        return {letter, tags: sortedTags};
+      })
+  );
+}

package/src/utils/tocUtils.ts

@@ -0,0 +1,119 @@
+/**
+ * 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 {useMemo} from 'react';
+import type {TOCItem} from '@docusaurus/mdx-loader';
+
+export type TOCTreeNode = {
+  readonly value: string;
+  readonly id: string;
+  readonly level: number;
+  readonly children: readonly TOCTreeNode[];
+};
+
+function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
+  const headings = flatTOC.map((heading) => ({
+    ...heading,
+    parentIndex: -1,
+    children: [] as TOCTreeNode[],
+  }));
+
+  // Keep track of which previous index would be the current heading's direct
+  // parent. Each entry <i> is the last index of the `headings` array at heading
+  // 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<number>(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.
+    const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
+    curr.parentIndex = Math.max(...ancestorLevelIndexes);
+    // Mark that curr.level was last seen at the current index.
+    prevIndexForLevel[curr.level] = currIndex;
+  });
+
+  const rootNodes: TOCTreeNode[] = [];
+
+  // For a given parentIndex, add each Node into that parent's `children` array
+  headings.forEach((heading) => {
+    const {parentIndex, ...rest} = heading;
+    if (parentIndex >= 0) {
+      headings[parentIndex]!.children.push(rest);
+    } else {
+      rootNodes.push(rest);
+    }
+  });
+  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]);
+}
+
+function filterTOC({
+  toc,
+  minHeadingLevel,
+  maxHeadingLevel,
+}: {
+  toc: readonly TOCTreeNode[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): TOCTreeNode[] {
+  function isValid(item: TOCTreeNode) {
+    return item.level >= minHeadingLevel && item.level <= maxHeadingLevel;
+  }
+
+  return toc.flatMap((item) => {
+    const filteredChildren = filterTOC({
+      toc: item.children,
+      minHeadingLevel,
+      maxHeadingLevel,
+    });
+    if (isValid(item)) {
+      return [
+        {
+          ...item,
+          children: filteredChildren,
+        },
+      ];
+    }
+    return filteredChildren;
+  });
+}
+
+/**
+ * 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,
+  maxHeadingLevel,
+}: {
+  toc: readonly TOCItem[];
+  minHeadingLevel: number;
+  maxHeadingLevel: number;
+}): readonly TOCTreeNode[] {
+  return useMemo(
+    () => 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;
@@ -39,14 +53,13 @@ export function useAlternatePageUtils(): {
       : `${baseUrlUnlocalized}${locale}/`;
   }
 
-  // TODO support correct alternate url when localized site is deployed on another domain
+  // TODO support correct alternate url when localized site is deployed on
+  // another domain
   function createUrl({
     locale,
     fullyQualified,
   }: {
     locale: string;
-    // For hreflang SEO headers, we need it to be fully qualified (full protocol/domain/path...)
-    // For 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

@@ -5,33 +5,37 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {useEffect, useRef} from 'react';
+import {useEffect} from 'react';
 import {useLocation} from '@docusaurus/router';
-import {Location} from '@docusaurus/history';
-import {usePrevious} from './usePrevious';
+import {useEvent, usePrevious} from './reactUtils';
+import type {Location} from 'history';
 
-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);
-  const isFirst = useRef<boolean>(true);
+
+  const onLocationChangeDynamic = useEvent(onLocationChange);
 
   useEffect(() => {
-    // Prevent first effect to trigger the listener on mount
-    if (isFirst.current) {
-      isFirst.current = false;
+    if (!previousLocation) {
       return;
     }
 
-    onLocationChange({
-      location,
-      previousLocation,
-    });
-  }, [location]);
+    if (location !== previousLocation) {
+      onLocationChangeDynamic({
+        location,
+        previousLocation,
+      });
+    }
+  }, [onLocationChangeDynamic, location, previousLocation]);
 }

package/src/utils/usePluralForm.ts

@@ -49,36 +49,34 @@ 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.
-//
-// 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.
-//
-// Notes:
-// - 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!
+/**
+ * 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.
+ *
+ * Notes:
+ * - 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!
+ */
 function useLocalePluralForms(): LocalePluralForms {
   const {
     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 (e) {
-        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]);
@@ -93,27 +91,41 @@ function selectPluralMessage(
   const parts = pluralMessages.split(separator);
 
   if (parts.length === 1) {
-    return parts[0];
-  } else {
-    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} `,
-      );
-    }
-    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[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.join(
+        ',',
+      )}), 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)]!;
 }
 
+/**
+ * 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();
   return {
-    selectMessage: (count: number, pluralMessages: string): string => {
-      return selectPluralMessage(pluralMessages, count, localePluralForm);
-    },
+    selectMessage: (count: number, pluralMessages: string): string =>
+      selectPluralMessage(pluralMessages, count, localePluralForm),
   };
 }