@docusaurus/theme-common 2.0.0-beta.17 → 2.0.0-beta.18

package/lib/utils/jsUtils.js

@@ -18,7 +18,7 @@ export function duplicates(arr, comparator = (a, b) => a === b) {
     return arr.filter((v, vIndex) => arr.findIndex((u) => comparator(u, v)) !== vIndex);
 }
 /**
- * Remove duplicate array items (similar to _.uniq)
+ * Remove duplicate array items (similar to `_.uniq`)
  * @param arr The array.
  * @returns An array with duplicate elements removed by reference comparison.
  */

package/lib/utils/metadataUtils.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 { type ReactNode } from 'react';
+interface PageMetadataProps {
+    readonly title?: string;
+    readonly description?: string;
+    readonly keywords?: readonly string[] | string;
+    readonly image?: string;
+    readonly children?: ReactNode;
+}
+/**
+ * Helper component to manipulate page metadata and override site defaults.
+ * Works in the same way as Helmet.
+ */
+export declare function PageMetadata({ title, description, keywords, image, children, }: PageMetadataProps): JSX.Element;
+/**
+ * Every layer of this provider will append a class name to the HTML element.
+ * There's no consumer for this hook: it's side-effect-only. This wrapper is
+ * necessary because Helmet does not "merge" classes.
+ * @see https://github.com/staylor/react-helmet-async/issues/161
+ */
+export declare function HtmlClassNameProvider({ className: classNameProp, children, }: {
+    className: string;
+    children: ReactNode;
+}): JSX.Element;
+/**
+ * A very thin wrapper around `HtmlClassNameProvider` that adds the plugin ID +
+ * name to the HTML class name.
+ */
+export declare function PluginHtmlClassNameProvider({ children, }: {
+    children: ReactNode;
+}): JSX.Element;
+export {};
+//# sourceMappingURL=metadataUtils.d.ts.map

package/lib/utils/metadataUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadataUtils.d.ts","sourceRoot":"","sources":["../../src/utils/metadataUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAc,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAO5C,UAAU,iBAAiB;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAAC;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAC3B,KAAK,EACL,WAAW,EACX,QAAQ,EACR,KAAK,EACL,QAAQ,GACT,EAAE,iBAAiB,GAAG,GAAG,CAAC,OAAO,CA6BjC;AAID;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EAAE,aAAa,EACxB,QAAQ,GACT,EAAE;IACD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,GAAG,CAAC,OAAO,CAWd;AASD;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,EAC1C,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,GAAG,CAAC,OAAO,CASd"}

package/lib/utils/metadataUtils.js

@@ -0,0 +1,61 @@
+/**
+ * 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 Head from '@docusaurus/Head';
+import clsx from 'clsx';
+import useRouteContext from '@docusaurus/useRouteContext';
+import { useBaseUrlUtils } from '@docusaurus/useBaseUrl';
+import { useTitleFormatter } from './generalUtils';
+/**
+ * Helper component to manipulate page metadata and override site defaults.
+ * Works in the same way as Helmet.
+ */
+export function PageMetadata({ title, description, keywords, image, children, }) {
+    const pageTitle = useTitleFormatter(title);
+    const { withBaseUrl } = useBaseUrlUtils();
+    const pageImage = image ? withBaseUrl(image, { absolute: true }) : undefined;
+    return (React.createElement(Head, null,
+        title && React.createElement("title", null, pageTitle),
+        title && React.createElement("meta", { property: "og:title", content: pageTitle }),
+        description && React.createElement("meta", { name: "description", content: description }),
+        description && React.createElement("meta", { property: "og:description", content: description }),
+        keywords && (React.createElement("meta", { name: "keywords", content: 
+            // https://github.com/microsoft/TypeScript/issues/17002
+            (Array.isArray(keywords) ? keywords.join(',') : keywords) })),
+        pageImage && React.createElement("meta", { property: "og:image", content: pageImage }),
+        pageImage && React.createElement("meta", { name: "twitter:image", content: pageImage }),
+        children));
+}
+const HtmlClassNameContext = React.createContext(undefined);
+/**
+ * Every layer of this provider will append a class name to the HTML element.
+ * There's no consumer for this hook: it's side-effect-only. This wrapper is
+ * necessary because Helmet does not "merge" classes.
+ * @see https://github.com/staylor/react-helmet-async/issues/161
+ */
+export function HtmlClassNameProvider({ className: classNameProp, children, }) {
+    const classNameContext = React.useContext(HtmlClassNameContext);
+    const className = clsx(classNameContext, classNameProp);
+    return (React.createElement(HtmlClassNameContext.Provider, { value: className },
+        React.createElement(Head, null,
+            React.createElement("html", { className: className })),
+        children));
+}
+function pluginNameToClassName(pluginName) {
+    return `plugin-${pluginName.replace(/docusaurus-(?:plugin|theme)-(?:content-)?/gi, '')}`;
+}
+/**
+ * A very thin wrapper around `HtmlClassNameProvider` that adds the plugin ID +
+ * name to the HTML class name.
+ */
+export function PluginHtmlClassNameProvider({ children, }) {
+    const routeContext = useRouteContext();
+    const nameClass = pluginNameToClassName(routeContext.plugin.name);
+    const idClass = `plugin-id-${routeContext.plugin.id}`;
+    return (React.createElement(HtmlClassNameProvider, { className: clsx(nameClass, idClass) }, children));
+}
+//# sourceMappingURL=metadataUtils.js.map

package/lib/utils/metadataUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadataUtils.js","sourceRoot":"","sources":["../../src/utils/metadataUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAuB,MAAM,OAAO,CAAC;AAC5C,OAAO,IAAI,MAAM,kBAAkB,CAAC;AACpC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,eAAe,MAAM,6BAA6B,CAAC;AAC1D,OAAO,EAAC,eAAe,EAAC,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAC,iBAAiB,EAAC,MAAM,gBAAgB,CAAC;AAUjD;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,EAC3B,KAAK,EACL,WAAW,EACX,QAAQ,EACR,KAAK,EACL,QAAQ,GACU;IAClB,MAAM,SAAS,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,EAAC,WAAW,EAAC,GAAG,eAAe,EAAE,CAAC;IACxC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,EAAE,EAAC,QAAQ,EAAE,IAAI,EAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAE3E,OAAO,CACL,oBAAC,IAAI;QACF,KAAK,IAAI,mCAAQ,SAAS,CAAS;QACnC,KAAK,IAAI,8BAAM,QAAQ,EAAC,UAAU,EAAC,OAAO,EAAE,SAAS,GAAI;QAEzD,WAAW,IAAI,8BAAM,IAAI,EAAC,aAAa,EAAC,OAAO,EAAE,WAAW,GAAI;QAChE,WAAW,IAAI,8BAAM,QAAQ,EAAC,gBAAgB,EAAC,OAAO,EAAE,WAAW,GAAI;QAEvE,QAAQ,IAAI,CACX,8BACE,IAAI,EAAC,UAAU,EACf,OAAO;YACL,uDAAuD;YACvD,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAW,GAErE,CACH;QAEA,SAAS,IAAI,8BAAM,QAAQ,EAAC,UAAU,EAAC,OAAO,EAAE,SAAS,GAAI;QAC7D,SAAS,IAAI,8BAAM,IAAI,EAAC,eAAe,EAAC,OAAO,EAAE,SAAS,GAAI;QAE9D,QAAQ,CACJ,CACR,CAAC;AACJ,CAAC;AAED,MAAM,oBAAoB,GAAG,KAAK,CAAC,aAAa,CAAqB,SAAS,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,EACpC,SAAS,EAAE,aAAa,EACxB,QAAQ,GAIT;IACC,MAAM,gBAAgB,GAAG,KAAK,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC;IAChE,MAAM,SAAS,GAAG,IAAI,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC;IACxD,OAAO,CACL,oBAAC,oBAAoB,CAAC,QAAQ,IAAC,KAAK,EAAE,SAAS;QAC7C,oBAAC,IAAI;YACH,8BAAM,SAAS,EAAE,SAAS,GAAI,CACzB;QACN,QAAQ,CACqB,CACjC,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAAC,UAAkB;IAC/C,OAAO,UAAU,UAAU,CAAC,OAAO,CACjC,6CAA6C,EAC7C,EAAE,CACH,EAAE,CAAC;AACN,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,EAC1C,QAAQ,GAGT;IACC,MAAM,YAAY,GAAG,eAAe,EAAE,CAAC;IACvC,MAAM,SAAS,GAAG,qBAAqB,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,aAAa,YAAY,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;IACtD,OAAO,CACL,oBAAC,qBAAqB,IAAC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,IACvD,QAAQ,CACa,CACzB,CAAC;AACJ,CAAC"}

package/lib/utils/navbarUtils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 { type ReactNode } from 'react';
+/**
+ * Split links by left/right. If position is unspecified, fallback to right.
+ */
+export declare function splitNavbarItems<T extends {
+    position?: 'left' | 'right';
+}>(items: T[]): [leftItems: T[], rightItems: T[]];
+/**
+ * Composes the `NavbarMobileSidebarProvider` and `NavbarSecondaryMenuProvider`.
+ * Because the latter depends on the former, they can't be re-ordered.
+ */
+export declare function NavbarProvider({ children }: {
+    children: ReactNode;
+}): JSX.Element;
+//# sourceMappingURL=navbarUtils.d.ts.map

package/lib/utils/navbarUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navbarUtils.d.ts","sourceRoot":"","sources":["../../src/utils/navbarUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAc,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAM5C;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS;IAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAC,EACtE,KAAK,EAAE,CAAC,EAAE,GACT,CAAC,SAAS,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CASnC;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAC,QAAQ,EAAC,EAAE;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAC,GAAG,GAAG,CAAC,OAAO,CAM7E"}

package/lib/utils/navbarUtils.js

@@ -0,0 +1,30 @@
+/**
+ * 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 { NavbarMobileSidebarProvider } from '../contexts/navbarMobileSidebar';
+import { NavbarSecondaryMenuProvider } from '../contexts/navbarSecondaryMenu';
+const DefaultNavItemPosition = 'right';
+/**
+ * Split links by left/right. If position is unspecified, fallback to right.
+ */
+export function splitNavbarItems(items) {
+    function isLeft(item) {
+        return (item.position ?? DefaultNavItemPosition) === 'left';
+    }
+    const leftItems = items.filter(isLeft);
+    const rightItems = items.filter((item) => !isLeft(item));
+    return [leftItems, rightItems];
+}
+/**
+ * Composes the `NavbarMobileSidebarProvider` and `NavbarSecondaryMenuProvider`.
+ * Because the latter depends on the former, they can't be re-ordered.
+ */
+export function NavbarProvider({ children }) {
+    return (React.createElement(NavbarMobileSidebarProvider, null,
+        React.createElement(NavbarSecondaryMenuProvider, null, children)));
+}
+//# sourceMappingURL=navbarUtils.js.map

package/lib/utils/navbarUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navbarUtils.js","sourceRoot":"","sources":["../../src/utils/navbarUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAuB,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAC,2BAA2B,EAAC,MAAM,iCAAiC,CAAC;AAC5E,OAAO,EAAC,2BAA2B,EAAC,MAAM,iCAAiC,CAAC;AAE5E,MAAM,sBAAsB,GAAG,OAAO,CAAC;AAEvC;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAU;IAEV,SAAS,MAAM,CAAC,IAAO;QACrB,OAAO,CAAC,IAAI,CAAC,QAAQ,IAAI,sBAAsB,CAAC,KAAK,MAAM,CAAC;IAC9D,CAAC;IAED,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IAEzD,OAAO,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,EAAC,QAAQ,EAAwB;IAC9D,OAAO,CACL,oBAAC,2BAA2B;QAC1B,oBAAC,2BAA2B,QAAE,QAAQ,CAA+B,CACzC,CAC/B,CAAC;AACJ,CAAC"}

package/lib/utils/reactUtils.d.ts

@@ -6,25 +6,36 @@
  */
 import { useLayoutEffect } 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...)
+ * 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`)
+ * render (before `useEffect`).
  */
 export declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;
 /**
  * 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
+ * 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
+ * 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 declare function useDynamicCallback<T extends (...args: never[]) => unknown>(callback: T): T;
+/**
+ * Gets `value` from the last render.
+ */
+export declare function usePrevious<T>(value: T): T | undefined;
+/**
+ * This error is thrown when a context is consumed outside its provider. Allows
+ * reusing a generic error message format and reduces bundle size. The hook's
+ * name will be extracted from its stack, so only the provider's name is needed.
+ */
 export declare class ReactContextError extends Error {
     constructor(providerName: string, additionalInfo?: string);
 }

package/lib/utils/reactUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reactUtils.d.ts","sourceRoot":"","sources":["../../src/utils/reactUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAyB,eAAe,EAAS,MAAM,OAAO,CAAC;AAEtE;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,wBACuB,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,EACxE,QAAQ,EAAE,CAAC,GACV,CAAC,CAUH;AAED,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,YAAY,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM;CAO1D"}
+{"version":3,"file":"reactUtils.d.ts","sourceRoot":"","sources":["../../src/utils/reactUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAyB,eAAe,EAAS,MAAM,OAAO,CAAC;AAGtE;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,wBAEzB,CAAC;AAEd;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,EACxE,QAAQ,EAAE,CAAC,GACV,CAAC,CAUH;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS,CAQtD;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,YAAY,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM;CAQ1D"}

package/lib/utils/reactUtils.js

@@ -5,22 +5,27 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 /**
- * This hook is like useLayoutEffect, but without the SSR warning
- * It seems hacky but it's used in many React libs (Redux, Formik...)
+ * 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`)
+ * render (before `useEffect`).
  */
-export const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+export const useIsomorphicLayoutEffect = ExecutionEnvironment.canUseDOM
+    ? 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
+ * 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
+ * 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
  */
@@ -33,11 +38,27 @@ export function useDynamicCallback(callback) {
     // but good enough for our use
     return useCallback((...args) => ref.current(...args), []);
 }
+/**
+ * Gets `value` from the last render.
+ */
+export function usePrevious(value) {
+    const ref = useRef();
+    useIsomorphicLayoutEffect(() => {
+        ref.current = value;
+    });
+    return ref.current;
+}
+/**
+ * This error is thrown when a context is consumed outside its provider. Allows
+ * reusing a generic error message format and reduces bundle size. The hook's
+ * name will be extracted from its stack, so only the provider's name is needed.
+ */
 export class ReactContextError extends Error {
     constructor(providerName, additionalInfo) {
         super();
         this.name = 'ReactContextError';
-        this.message = `Hook ${this.stack?.split('\n')[1]?.match(/at (?<name>\w+)/)?.groups.name} is called outside the <${providerName}>. ${additionalInfo || ''}`;
+        this.message = `Hook ${this.stack?.split('\n')[1]?.match(/at (?:\w+\.)?(?<name>\w+)/)?.groups
+            .name} is called outside the <${providerName}>. ${additionalInfo || ''}`;
     }
 }
 //# sourceMappingURL=reactUtils.js.map

package/lib/utils/reactUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"reactUtils.js","sourceRoot":"","sources":["../../src/utils/reactUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAC,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAC,MAAM,OAAO,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,yBAAyB,GACpC,OAAO,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,SAAS,CAAC;AAE9D;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAW;IAEX,MAAM,GAAG,GAAG,MAAM,CAAI,QAAQ,CAAC,CAAC;IAEhC,yBAAyB,CAAC,GAAG,EAAE;QAC7B,GAAG,CAAC,OAAO,GAAG,QAAQ,CAAC;IACzB,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,4EAA4E;IAC5E,8BAA8B;IAC9B,OAAO,WAAW,CAAI,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,YAAoB,EAAE,cAAuB;QACvD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,QACb,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,EAAE,MAAO,CAAC,IAChE,2BAA2B,YAAY,MAAM,cAAc,IAAI,EAAE,EAAE,CAAC;IACtE,CAAC;CACF"}
+{"version":3,"file":"reactUtils.js","sourceRoot":"","sources":["../../src/utils/reactUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAC,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,EAAC,MAAM,OAAO,CAAC;AACtE,OAAO,oBAAoB,MAAM,kCAAkC,CAAC;AAEpE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,oBAAoB,CAAC,SAAS;IACrE,CAAC,CAAC,eAAe;IACjB,CAAC,CAAC,SAAS,CAAC;AAEd;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAW;IAEX,MAAM,GAAG,GAAG,MAAM,CAAI,QAAQ,CAAC,CAAC;IAEhC,yBAAyB,CAAC,GAAG,EAAE;QAC7B,GAAG,CAAC,OAAO,GAAG,QAAQ,CAAC;IACzB,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,4EAA4E;IAC5E,8BAA8B;IAC9B,OAAO,WAAW,CAAI,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAI,KAAQ;IACrC,MAAM,GAAG,GAAG,MAAM,EAAK,CAAC;IAExB,yBAAyB,CAAC,GAAG,EAAE;QAC7B,GAAG,CAAC,OAAO,GAAG,KAAK,CAAC;IACtB,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC,OAAO,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,YAAoB,EAAE,cAAuB;QACvD,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,QACb,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,2BAA2B,CAAC,EAAE,MAAO;aACpE,IACL,2BAA2B,YAAY,MAAM,cAAc,IAAI,EAAE,EAAE,CAAC;IACtE,CAAC;CACF"}

package/lib/utils/regexpUtils.d.ts

@@ -5,7 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Converts an optional string into a Regex case insensitive and global
+ * Matches a string regex (as provided from the config) against a target in a
+ * null-safe fashion, case insensitive and global.
  */
 export declare function isRegexpStringMatch(regexAsString?: string, valueToTest?: string): boolean;
 //# sourceMappingURL=regexpUtils.d.ts.map

package/lib/utils/regexpUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"regexpUtils.d.ts","sourceRoot":"","sources":["../../src/utils/regexpUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,CAAC,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAST"}
+{"version":3,"file":"regexpUtils.d.ts","sourceRoot":"","sources":["../../src/utils/regexpUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,aAAa,CAAC,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAST"}

package/lib/utils/regexpUtils.js

@@ -5,7 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 /**
- * Converts an optional string into a Regex case insensitive and global
+ * Matches a string regex (as provided from the config) against a target in a
+ * null-safe fashion, case insensitive and global.
  */
 export function isRegexpStringMatch(regexAsString, valueToTest) {
     if (typeof regexAsString === 'undefined' ||

package/lib/utils/regexpUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"regexpUtils.js","sourceRoot":"","sources":["../../src/utils/regexpUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,aAAsB,EACtB,WAAoB;IAEpB,IACE,OAAO,aAAa,KAAK,WAAW;QACpC,OAAO,WAAW,KAAK,WAAW,EAClC;QACA,OAAO,KAAK,CAAC;KACd;IAED,OAAO,IAAI,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"regexpUtils.js","sourceRoot":"","sources":["../../src/utils/regexpUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CACjC,aAAsB,EACtB,WAAoB;IAEpB,IACE,OAAO,aAAa,KAAK,WAAW;QACpC,OAAO,WAAW,KAAK,WAAW,EAClC;QACA,OAAO,KAAK,CAAC;KACd;IAED,OAAO,IAAI,MAAM,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;AAC3D,CAAC"}

package/lib/utils/routesUtils.d.ts

@@ -4,11 +4,23 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference types="@docusaurus/module-type-aliases" />
-import { type Route } from '@generated/routes';
+import type { Route } from '@docusaurus/types';
+/**
+ * Compare the 2 paths, case insensitive and ignoring trailing slash
+ */
+export declare function isSamePath(path1: string | undefined, path2: string | undefined): boolean;
+/**
+ * Note that sites don't always have a homepage in practice, so we can't assume
+ * that linking to '/' is always safe.
+ * @see https://github.com/facebook/docusaurus/pull/6517#issuecomment-1048709116
+ */
 export declare function findHomePageRoute({ baseUrl, routes: initialRoutes, }: {
     routes: Route[];
     baseUrl: string;
 }): Route | undefined;
+/**
+ * Fetches the route that points to "/". Use this instead of the naive "/",
+ * because the homepage may not exist.
+ */
 export declare function useHomePageRoute(): Route | undefined;
 //# sourceMappingURL=routesUtils.d.ts.map

package/lib/utils/routesUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routesUtils.d.ts","sourceRoot":"","sources":["../../src/utils/routesUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;;AAEH,OAAwB,EAAC,KAAK,KAAK,EAAC,MAAM,mBAAmB,CAAC;AAM9D,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,MAAM,EAAE,aAAa,GACtB,EAAE;IACD,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,KAAK,GAAG,SAAS,CAwBpB;AAED,wBAAgB,gBAAgB,IAAI,KAAK,GAAG,SAAS,CAUpD"}
+{"version":3,"file":"routesUtils.d.ts","sourceRoot":"","sources":["../../src/utils/routesUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAC,KAAK,EAAC,MAAM,mBAAmB,CAAC;AAE7C;;GAEG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,OAAO,CAOT;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,OAAO,EACP,MAAM,EAAE,aAAa,GACtB,EAAE;IACD,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,GAAG,KAAK,GAAG,SAAS,CAwBpB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,KAAK,GAAG,SAAS,CAMpD"}

package/lib/utils/routesUtils.js

@@ -4,11 +4,23 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import GeneratedRoutes from '@generated/routes';
 import { useMemo } from 'react';
+import generatedRoutes from '@generated/routes';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-// Note that all sites don't always have a homepage in practice
-// See https://github.com/facebook/docusaurus/pull/6517#issuecomment-1048709116
+/**
+ * Compare the 2 paths, case insensitive and ignoring trailing slash
+ */
+export function isSamePath(path1, path2) {
+    const normalize = (pathname) => (!pathname || pathname?.endsWith('/')
+        ? pathname
+        : `${pathname}/`)?.toLowerCase();
+    return normalize(path1) === normalize(path2);
+}
+/**
+ * Note that sites don't always have a homepage in practice, so we can't assume
+ * that linking to '/' is always safe.
+ * @see https://github.com/facebook/docusaurus/pull/6517#issuecomment-1048709116
+ */
 export function findHomePageRoute({ baseUrl, routes: initialRoutes, }) {
     function isHomePageRoute(route) {
         return route.path === baseUrl && route.exact === true;
@@ -31,11 +43,12 @@ export function findHomePageRoute({ baseUrl, routes: initialRoutes, }) {
     }
     return doFindHomePageRoute(initialRoutes);
 }
+/**
+ * Fetches the route that points to "/". Use this instead of the naive "/",
+ * because the homepage may not exist.
+ */
 export function useHomePageRoute() {
     const { baseUrl } = useDocusaurusContext().siteConfig;
-    return useMemo(() => findHomePageRoute({
-        routes: GeneratedRoutes,
-        baseUrl,
-    }), [baseUrl]);
+    return useMemo(() => findHomePageRoute({ routes: generatedRoutes, baseUrl }), [baseUrl]);
 }
 //# sourceMappingURL=routesUtils.js.map

package/lib/utils/routesUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"routesUtils.js","sourceRoot":"","sources":["../../src/utils/routesUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,eAA6B,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAC,OAAO,EAAC,MAAM,OAAO,CAAC;AAC9B,OAAO,oBAAoB,MAAM,kCAAkC,CAAC;AAEpE,+DAA+D;AAC/D,+EAA+E;AAC/E,MAAM,UAAU,iBAAiB,CAAC,EAChC,OAAO,EACP,MAAM,EAAE,aAAa,GAItB;IACC,SAAS,eAAe,CAAC,KAAY;QACnC,OAAO,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC;IACxD,CAAC;IAED,SAAS,iBAAiB,CAAC,KAAY;QACrC,OAAO,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAChD,CAAC;IAED,SAAS,mBAAmB,CAAC,MAAe;QAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE;YACvB,OAAO,SAAS,CAAC;SAClB;QACD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC9C,IAAI,QAAQ,EAAE;YACZ,OAAO,QAAQ,CAAC;SACjB;QACD,MAAM,cAAc,GAAG,MAAM;aAC1B,MAAM,CAAC,iBAAiB,CAAC;aACzB,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAC1C,OAAO,mBAAmB,CAAC,cAAc,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,mBAAmB,CAAC,aAAa,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,MAAM,EAAC,OAAO,EAAC,GAAG,oBAAoB,EAAE,CAAC,UAAU,CAAC;IACpD,OAAO,OAAO,CACZ,GAAG,EAAE,CACH,iBAAiB,CAAC;QAChB,MAAM,EAAE,eAAe;QACvB,OAAO;KACR,CAAC,EACJ,CAAC,OAAO,CAAC,CACV,CAAC;AACJ,CAAC"}
+{"version":3,"file":"routesUtils.js","sourceRoot":"","sources":["../../src/utils/routesUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAC,OAAO,EAAC,MAAM,OAAO,CAAC;AAC9B,OAAO,eAAe,MAAM,mBAAmB,CAAC;AAChD,OAAO,oBAAoB,MAAM,kCAAkC,CAAC;AAGpE;;GAEG;AACH,MAAM,UAAU,UAAU,CACxB,KAAyB,EACzB,KAAyB;IAEzB,MAAM,SAAS,GAAG,CAAC,QAA4B,EAAE,EAAE,CACjD,CAAC,CAAC,QAAQ,IAAI,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC;QACnC,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,GAAG,QAAQ,GAAG,CACjB,EAAE,WAAW,EAAE,CAAC;IACnB,OAAO,SAAS,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAChC,OAAO,EACP,MAAM,EAAE,aAAa,GAItB;IACC,SAAS,eAAe,CAAC,KAAY;QACnC,OAAO,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC;IACxD,CAAC;IAED,SAAS,iBAAiB,CAAC,KAAY;QACrC,OAAO,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAChD,CAAC;IAED,SAAS,mBAAmB,CAAC,MAAe;QAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE;YACvB,OAAO,SAAS,CAAC;SAClB;QACD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;QAC9C,IAAI,QAAQ,EAAE;YACZ,OAAO,QAAQ,CAAC;SACjB;QACD,MAAM,cAAc,GAAG,MAAM;aAC1B,MAAM,CAAC,iBAAiB,CAAC;aACzB,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAC1C,OAAO,mBAAmB,CAAC,cAAc,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO,mBAAmB,CAAC,aAAa,CAAC,CAAC;AAC5C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,EAAC,OAAO,EAAC,GAAG,oBAAoB,EAAE,CAAC,UAAU,CAAC;IACpD,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,iBAAiB,CAAC,EAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAC,CAAC,EAC3D,CAAC,OAAO,CAAC,CACV,CAAC;AACJ,CAAC"}

package/lib/utils/scrollUtils.d.ts

@@ -5,49 +5,55 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React, { type ReactNode } from 'react';
-/**
- * We need a way to update the scroll position while ignoring scroll events
- * without affecting Navbar/BackToTop visibility
- *
- * This API permits to temporarily disable/ignore scroll events
- * Motivated by https://github.com/facebook/docusaurus/pull/5618
- */
 declare type ScrollController = {
-    /**
-     * A boolean ref tracking whether scroll events are enabled
-     */
+    /** A boolean ref tracking whether scroll events are enabled. */
     scrollEventsEnabledRef: React.MutableRefObject<boolean>;
-    /**
-     * Enables scroll events in `useScrollPosition`
-     */
+    /** Enable scroll events in `useScrollPosition`. */
     enableScrollEvents: () => void;
-    /**
-     * Disables scroll events in `useScrollPosition`
-     */
+    /** Disable scroll events in `useScrollPosition`. */
     disableScrollEvents: () => void;
 };
 export declare function ScrollControllerProvider({ children, }: {
     children: ReactNode;
 }): JSX.Element;
+/**
+ * We need a way to update the scroll position while ignoring scroll events
+ * so as not to toggle Navbar/BackToTop visibility.
+ *
+ * This API permits to temporarily disable/ignore scroll events. Motivated by
+ * https://github.com/facebook/docusaurus/pull/5618
+ */
 export declare function useScrollController(): ScrollController;
 declare type ScrollPosition = {
     scrollX: number;
     scrollY: number;
 };
+/**
+ * This hook fires an effect when the scroll position changes. The effect will
+ * be provided with the before/after scroll positions. Note that the effect may
+ * not be always run: if scrolling is disabled through `useScrollController`, it
+ * will be a no-op.
+ *
+ * @see {@link useScrollController}
+ */
 export declare function useScrollPosition(effect: (position: ScrollPosition, lastPosition: ScrollPosition | null) => void, deps?: unknown[]): void;
-declare type UseScrollPositionBlockerReturn = {
-    blockElementScrollPositionUntilNextRender: (el: HTMLElement) => void;
-};
 /**
- * This hook permits to "block" the scroll position of a dom element
+ * This hook permits to "block" the scroll position of a DOM element.
  * The idea is that we should be able to update DOM content above this element
- * but the screen position of this element should not change
+ * but the screen position of this element should not change.
+ *
+ * Feature motivated by the Tabs groups: clicking on a tab may affect tabs of
+ * the same group upper in the tree, yet to avoid a bad UX, the clicked tab must
+ * remain under the user mouse.
  *
- * Feature motivated by the Tabs groups:
- * clicking on a tab may affect tabs of the same group upper in the tree
- * Yet to avoid a bad UX, the clicked tab must remain under the user mouse!
- * See GIF here: https://github.com/facebook/docusaurus/pull/5618
+ * @see https://github.com/facebook/docusaurus/pull/5618
  */
-export declare function useScrollPositionBlocker(): UseScrollPositionBlockerReturn;
+export declare function useScrollPositionBlocker(): {
+    /**
+     * Takes an element, and keeps its screen position no matter what's getting
+     * rendered above it, until the next render.
+     */
+    blockElementScrollPositionUntilNextRender: (el: HTMLElement) => void;
+};
 export {};
 //# sourceMappingURL=scrollUtils.d.ts.map

package/lib/utils/scrollUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scrollUtils.d.ts","sourceRoot":"","sources":["../../src/utils/scrollUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAEZ,KAAK,SAAS,EAOf,MAAM,OAAO,CAAC;AAIf;;;;;;GAMG;AACH,aAAK,gBAAgB,GAAG;IACtB;;OAEG;IACH,sBAAsB,EAAE,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACxD;;OAEG;IACH,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B;;OAEG;IACH,mBAAmB,EAAE,MAAM,IAAI,CAAC;CACjC,CAAC;AAuBF,wBAAgB,wBAAwB,CAAC,EACvC,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,GAAG,CAAC,OAAO,CAMd;AAED,wBAAgB,mBAAmB,IAAI,gBAAgB,CAMtD;AAUD,aAAK,cAAc,GAAG;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC;AAEzD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,CACN,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,cAAc,GAAG,IAAI,KAChC,IAAI,EACT,IAAI,GAAE,OAAO,EAAO,GACnB,IAAI,CAkCN;AA+CD,aAAK,8BAA8B,GAAG;IACpC,yCAAyC,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;CACtE,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,IAAI,8BAA8B,CAwCzE"}
+{"version":3,"file":"scrollUtils.d.ts","sourceRoot":"","sources":["../../src/utils/scrollUtils.tsx"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,EAOZ,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAIf,aAAK,gBAAgB,GAAG;IACtB,gEAAgE;IAChE,sBAAsB,EAAE,KAAK,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACxD,mDAAmD;IACnD,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,IAAI,CAAC;CACjC,CAAC;AAuBF,wBAAgB,wBAAwB,CAAC,EACvC,QAAQ,GACT,EAAE;IACD,QAAQ,EAAE,SAAS,CAAC;CACrB,GAAG,GAAG,CAAC,OAAO,CAOd;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,gBAAgB,CAMtD;AAED,aAAK,cAAc,GAAG;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAC,CAAC;AAUzD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,CACN,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,cAAc,GAAG,IAAI,KAChC,IAAI,EACT,IAAI,GAAE,OAAO,EAAO,GACnB,IAAI,CA8BN;AA6CD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,IAAI;IAC1C;;;OAGG;IACH,yCAAyC,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,IAAI,CAAC;CACtE,CAwCA"}

package/lib/utils/scrollUtils.js

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, } from 'react';
+import React, { useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, } from 'react';
 import { useDynamicCallback, ReactContextError } from './reactUtils';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 function useScrollControllerContextValue() {
@@ -19,10 +19,18 @@ function useScrollControllerContextValue() {
         },
     }), []);
 }
-const ScrollMonitorContext = createContext(undefined);
+const ScrollMonitorContext = React.createContext(undefined);
 export function ScrollControllerProvider({ children, }) {
-    return (React.createElement(ScrollMonitorContext.Provider, { value: useScrollControllerContextValue() }, children));
+    const value = useScrollControllerContextValue();
+    return (React.createElement(ScrollMonitorContext.Provider, { value: value }, children));
 }
+/**
+ * We need a way to update the scroll position while ignoring scroll events
+ * so as not to toggle Navbar/BackToTop visibility.
+ *
+ * This API permits to temporarily disable/ignore scroll events. Motivated by
+ * https://github.com/facebook/docusaurus/pull/5618
+ */
 export function useScrollController() {
     const context = useContext(ScrollMonitorContext);
     if (context == null) {
@@ -36,6 +44,14 @@ const getScrollPosition = () => ExecutionEnvironment.canUseDOM
         scrollY: window.pageYOffset,
     }
     : null;
+/**
+ * This hook fires an effect when the scroll position changes. The effect will
+ * be provided with the before/after scroll positions. Note that the effect may
+ * not be always run: if scrolling is disabled through `useScrollController`, it
+ * will be a no-op.
+ *
+ * @see {@link useScrollController}
+ */
 export function useScrollPosition(effect, deps = []) {
     const { scrollEventsEnabledRef } = useScrollController();
     const lastPositionRef = useRef(getScrollPosition());
@@ -57,12 +73,8 @@ export function useScrollPosition(effect, deps = []) {
         handleScroll();
         window.addEventListener('scroll', handleScroll, opts);
         return () => window.removeEventListener('scroll', handleScroll, opts);
-    }, [
-        dynamicEffect,
-        scrollEventsEnabledRef,
         // eslint-disable-next-line react-hooks/exhaustive-deps
-        ...deps,
-    ]);
+    }, [dynamicEffect, scrollEventsEnabledRef, ...deps]);
 }
 function useScrollPositionSaver() {
     const lastElementRef = useRef({
@@ -91,14 +103,15 @@ function useScrollPositionSaver() {
     return useMemo(() => ({ save, restore }), [restore, save]);
 }
 /**
- * This hook permits to "block" the scroll position of a dom element
+ * This hook permits to "block" the scroll position of a DOM element.
  * The idea is that we should be able to update DOM content above this element
- * but the screen position of this element should not change
+ * but the screen position of this element should not change.
+ *
+ * Feature motivated by the Tabs groups: clicking on a tab may affect tabs of
+ * the same group upper in the tree, yet to avoid a bad UX, the clicked tab must
+ * remain under the user mouse.
  *
- * Feature motivated by the Tabs groups:
- * clicking on a tab may affect tabs of the same group upper in the tree
- * Yet to avoid a bad UX, the clicked tab must remain under the user mouse!
- * See GIF here: https://github.com/facebook/docusaurus/pull/5618
+ * @see https://github.com/facebook/docusaurus/pull/5618
  */
 export function useScrollPositionBlocker() {
     const scrollController = useScrollController();
@@ -110,9 +123,9 @@ export function useScrollPositionBlocker() {
         nextLayoutEffectCallbackRef.current = () => {
             const { restored } = scrollPositionSaver.restore();
             nextLayoutEffectCallbackRef.current = undefined;
-            // Restoring the former scroll position will trigger a scroll event
-            // We need to wait for next scroll event to happen
-            // before enabling again the scrollController events
+            // Restoring the former scroll position will trigger a scroll event. We
+            // need to wait for next scroll event to happen before enabling the
+            // scrollController events again.
             if (restored) {
                 const handleScrollRestoreEvent = () => {
                     scrollController.enableScrollEvents();

package/lib/utils/scrollUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"scrollUtils.js","sourceRoot":"","sources":["../../src/utils/scrollUtils.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"scrollUtils.js","sourceRoot":"","sources":["../../src/utils/scrollUtils.tsx"],"names":[],"mappings":"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"}