@docusaurus/theme-common 0.0.0-4523 → 0.0.0-4527

package/src/utils/reactUtils.tsx

@@ -7,19 +7,27 @@
 
 import {useCallback, useEffect, useLayoutEffect, useRef} from 'react';
 
-// This hook is like useLayoutEffect, but without the SSR warning
-// It seems hacky but it's used in many React libs (Redux, Formik...)
-// Also mentioned here: https://github.com/facebook/react/issues/16956
-// It is useful when you need to update a ref as soon as possible after a React render (before useEffect)
+/**
+ * This hook is like useLayoutEffect, but without the SSR warning
+ * It seems hacky but it's used in many React libs (Redux, Formik...)
+ * Also mentioned here: https://github.com/facebook/react/issues/16956
+ * It is useful when you need to update a ref as soon as possible after a React
+ * render (before `useEffect`)
+ */
 export const useIsomorphicLayoutEffect =
   typeof window !== 'undefined' ? useLayoutEffect : useEffect;
 
-// Permits to transform an unstable callback (like an arrow function provided as props)
-// to a "stable" callback that is safe to use in a useEffect dependency array
-// Useful to avoid React stale closure problems + avoid useless effect re-executions
-//
-// Workaround until the React team recommends a good solution, see https://github.com/facebook/react/issues/16956
-// This generally works has some potential drawbacks, such as https://github.com/facebook/react/issues/16956#issuecomment-536636418
+/**
+ * Permits to transform an unstable callback (like an arrow function provided as
+ * props) to a "stable" callback that is safe to use in a useEffect dependency
+ * array. Useful to avoid React stale closure problems + avoid useless effect
+ * re-executions
+ *
+ * Workaround until the React team recommends a good solution, see
+ * https://github.com/facebook/react/issues/16956
+ * This generally works but has some potential drawbacks, such as
+ * https://github.com/facebook/react/issues/16956#issuecomment-536636418
+ */
 export function useDynamicCallback<T extends (...args: never[]) => unknown>(
   callback: T,
 ): T {
@@ -29,6 +37,7 @@ export function useDynamicCallback<T extends (...args: never[]) => unknown>(
     ref.current = callback;
   }, [callback]);
 
-  // @ts-expect-error: TS is right that this callback may be a supertype of T, but good enough for our use
+  // @ts-expect-error: TS is right that this callback may be a supertype of T,
+  // but good enough for our use
   return useCallback<T>((...args) => ref.current(...args), []);
 }

package/src/utils/regexpUtils.ts

@@ -6,7 +6,7 @@
  */
 
 /**
- * Utility to convert an optional string into a Regex case insensitive and global
+ * Converts an optional string into a Regex case insensitive and global
  */
 export function isRegexpStringMatch(
   regexAsString?: string,

package/src/utils/storageUtils.ts

@@ -11,8 +11,8 @@ 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 browser storage is unavailable (like running Docusaurus in
+// iframe) See https://github.com/facebook/docusaurus/pull/4501
 function getBrowserStorage(
   storageType: StorageType = DefaultStorageType,
 ): Storage | null {
@@ -23,13 +23,12 @@ function getBrowserStorage(
   }
   if (storageType === 'none') {
     return null;
-  } else {
-    try {
-      return window[storageType];
-    } catch (e) {
-      logOnceBrowserStorageNotAvailableWarning(e as Error);
-      return null;
-    }
+  }
+  try {
+    return window[storageType];
+  } catch (e) {
+    logOnceBrowserStorageNotAvailableWarning(e as Error);
+    return null;
   }
 }
 
@@ -79,10 +78,10 @@ Please only call storage APIs in effects and event handlers.`);
 
 /**
  * Creates an object for accessing a particular key in localStorage.
- * The API is fail-safe, and 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
+ * The API is fail-safe, and 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 = (
   key: string,

package/src/utils/tocUtils.ts

@@ -36,9 +36,8 @@ export function filterTOC({
           children: filteredChildren,
         },
       ];
-    } else {
-      return filteredChildren;
     }
+    return filteredChildren;
   });
 }
 

package/src/utils/useAlternatePageUtils.ts

@@ -39,14 +39,15 @@ 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
+    // 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/useContextualSearchFilters.ts

@@ -18,8 +18,8 @@ export type useContextualSearchFiltersReturns = {
   tags: string[];
 };
 
-// We may want to support multiple search engines, don't couple that to Algolia/DocSearch
-// Maybe users will want to use its own search engine solution
+// We may want to support multiple search engines, don't couple that to
+// Algolia/DocSearch. Maybe users want to use their own search engine solution
 export function useContextualSearchFilters(): useContextualSearchFiltersReturns {
   const {i18n} = useDocusaurusContext();
   const allDocsData = useAllDocsData();

package/src/utils/usePluralForm.ts

@@ -49,23 +49,29 @@ 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-)
+    // @ts-expect-error checking Intl.PluralRules in case browser doesn't
+    // have it (e.g Safari 12-)
     if (Intl.PluralRules) {
       try {
         return createLocalePluralForms(currentLocale);
@@ -94,17 +100,17 @@ function selectPluralMessage(
 
   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)];
   }
+  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)];
 }
 
 export function usePluralForm(): {

package/src/utils/useTOCHighlight.ts

@@ -13,7 +13,8 @@ TODO make the hardcoded theme-classic classnames configurable
 (or add them to ThemeClassNames?)
  */
 
-// If the anchor has no height and is just a "marker" in the dom; we'll use the parent (normally the link text) rect boundaries instead
+// If the anchor has no height and is just a "marker" in the dom; we'll use the
+// parent (normally the link text) rect boundaries instead
 function getVisibleBoundingClientRect(element: HTMLElement): DOMRect {
   const rect = element.getBoundingClientRect();
   const hasNoHeight = rect.top === rect.bottom;
@@ -23,8 +24,10 @@ function getVisibleBoundingClientRect(element: HTMLElement): DOMRect {
   return rect;
 }
 
-// Considering we divide viewport into 2 zones of each 50vh
-// This returns true if an element is in the first zone (ie, appear in viewport, near the top)
+/**
+ * Considering we divide viewport into 2 zones of each 50vh, this returns true
+ * if an element is in the first zone (ie, appear in viewport, near the top)
+ */
 function isInViewportTopHalf(boundingRect: DOMRect) {
   return boundingRect.top > 0 && boundingRect.bottom < window.innerHeight / 2;
 }
@@ -54,9 +57,10 @@ function getActiveAnchor(
     anchorTopOffset: number;
   },
 ): Element | null {
-  // Naming is hard
-  // The "nextVisibleAnchor" is the first anchor that appear under the viewport top boundary
-  // Note: it does not mean this anchor is visible yet, but if user continues scrolling down, it will be the first to become visible
+  // Naming is hard: The "nextVisibleAnchor" is the first anchor that appear
+  // under the viewport top boundary. It does not mean this anchor is visible
+  // yet, but if user continues scrolling down, it will be the first to become
+  // visible
   const nextVisibleAnchor = anchors.find((anchor) => {
     const boundingRect = getVisibleBoundingClientRect(anchor);
     return boundingRect.top >= anchorTopOffset;
@@ -64,23 +68,22 @@ function getActiveAnchor(
 
   if (nextVisibleAnchor) {
     const boundingRect = getVisibleBoundingClientRect(nextVisibleAnchor);
-    // If anchor is in the top half of the viewport: it is the one we consider "active"
-    // (unless it's too close to the top and and soon to be scrolled outside viewport)
+    // If anchor is in the top half of the viewport: it is the one we consider
+    // "active" (unless it's too close to the top and and soon to be scrolled
+    // outside viewport)
     if (isInViewportTopHalf(boundingRect)) {
       return nextVisibleAnchor;
     }
-    // If anchor is in the bottom half of the viewport, or under the viewport, we consider the active anchor is the previous one
-    // This is because the main text appearing in the user screen mostly belong to the previous anchor
-    else {
-      // Returns null for the first anchor, see https://github.com/facebook/docusaurus/issues/5318
-      return anchors[anchors.indexOf(nextVisibleAnchor) - 1] ?? null;
-    }
+    // If anchor is in the bottom half of the viewport, or under the viewport,
+    // we consider the active anchor is the previous one. This is because the
+    // main text appearing in the user screen mostly belong to the previous
+    // anchor. Returns null for the first anchor, see
+    // https://github.com/facebook/docusaurus/issues/5318
+    return anchors[anchors.indexOf(nextVisibleAnchor) - 1] ?? null;
   }
   // no anchor under viewport top? (ie we are at the bottom of the page)
   // => highlight the last anchor found
-  else {
-    return anchors[anchors.length - 1];
-  }
+  return anchors[anchors.length - 1];
 }
 
 function getLinkAnchorValue(link: HTMLAnchorElement): string {