@docusaurus/theme-common 2.0.0-beta.8e9b829d9 → 2.0.0-beta.9

package/lib/utils/ThemeClassNames.js

@@ -5,19 +5,52 @@
  * LICENSE file in the root directory of this source tree.
  */
 // These class names are used to style page layouts in Docusaurus
+// Those are meant to be targeted by user-provided custom CSS selectors
+// /!\ Please do not modify the classnames! This is a breaking change, and annoying for users!
 export const ThemeClassNames = {
     page: {
         blogListPage: 'blog-list-page',
         blogPostPage: 'blog-post-page',
         blogTagsListPage: 'blog-tags-list-page',
-        blogTagsPostPage: 'blog-tags-post-page',
-        docPage: 'doc-page',
+        blogTagPostListPage: 'blog-tags-post-list-page',
+        docsDocPage: 'docs-doc-page',
+        docsTagsListPage: 'docs-tags-list-page',
+        docsTagDocListPage: 'docs-tags-doc-list-page',
         mdxPage: 'mdx-page',
     },
     wrapper: {
         main: 'main-wrapper',
         blogPages: 'blog-wrapper',
-        docPages: 'docs-wrapper',
+        docsPages: 'docs-wrapper',
         mdxPages: 'mdx-wrapper',
     },
+    // /!\ Please keep the naming convention consistent!
+    // Something like: "theme-{blog,doc,version,page}?-<suffix>"
+    common: {
+        editThisPage: 'theme-edit-this-page',
+        lastUpdated: 'theme-last-updated',
+        backToTopButton: 'theme-back-to-top-button',
+    },
+    layout: {
+    // TODO add other stable classNames here
+    },
+    docs: {
+        docVersionBanner: 'theme-doc-version-banner',
+        docVersionBadge: 'theme-doc-version-badge',
+        docMarkdown: 'theme-doc-markdown',
+        docTocMobile: 'theme-doc-toc-mobile',
+        docTocDesktop: 'theme-doc-toc-desktop',
+        docFooter: 'theme-doc-footer',
+        docFooterTagsRow: 'theme-doc-footer-tags-row',
+        docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
+        docSidebarMenu: 'theme-doc-sidebar-menu',
+        docSidebarItemCategory: 'theme-doc-sidebar-item-category',
+        docSidebarItemLink: 'theme-doc-sidebar-item-link',
+        docSidebarItemCategoryLevel: (level) => `theme-doc-sidebar-item-category-level-${level}`,
+        docSidebarItemLinkLevel: (level) => `theme-doc-sidebar-item-link-level-${level}`,
+        // TODO add other stable classNames here
+    },
+    blog: {
+    // TODO add other stable classNames here
+    },
 };

package/lib/utils/announcementBarUtils.d.ts

@@ -7,7 +7,7 @@
 import { ReactNode } from 'react';
 export declare const AnnouncementBarDismissStorageKey = "docusaurus.announcement.dismiss";
 declare type AnnouncementBarAPI = {
-    readonly isClosed: boolean;
+    readonly isActive: boolean;
     readonly close: () => void;
 };
 export declare const AnnouncementBarProvider: ({ children, }: {

package/lib/utils/announcementBarUtils.js

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React, { useState, useEffect, useCallback, useMemo, useContext, createContext, } from 'react';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import { createStorageSlot } from './storageUtils';
 import { useThemeConfig } from './useThemeConfig';
 export const AnnouncementBarDismissStorageKey = 'docusaurus.announcement.dismiss';
@@ -16,9 +16,9 @@ const isDismissedInStorage = () => AnnouncementBarDismissStorage.get() === 'true
 const setDismissedInStorage = (bool) => AnnouncementBarDismissStorage.set(String(bool));
 const useAnnouncementBarContextValue = () => {
     const { announcementBar } = useThemeConfig();
-    const { isClient } = useDocusaurusContext();
+    const isBrowser = useIsBrowser();
     const [isClosed, setClosed] = useState(() => {
-        return isClient
+        return isBrowser
             ? // On client navigation: init with localstorage value
                 isDismissedInStorage()
             : // On server/hydration: always visible to prevent layout shifts (will be hidden with css if needed)
@@ -51,13 +51,13 @@ const useAnnouncementBarContextValue = () => {
         if (isNewAnnouncement || !isDismissedInStorage()) {
             setClosed(false);
         }
-    }, []);
+    }, [announcementBar]);
     return useMemo(() => {
         return {
-            isClosed,
+            isActive: !!announcementBar && !isClosed,
             close: handleClose,
         };
-    }, [isClosed]);
+    }, [announcementBar, isClosed, handleClose]);
 };
 const AnnouncementBarContext = createContext(null);
 export const AnnouncementBarProvider = ({ children, }) => {

package/lib/utils/docsPreferredVersion/DocsPreferredVersionProvider.js

@@ -69,7 +69,7 @@ function useContextValue() {
         return {
             savePreferredVersion,
         };
-    }, [setState]);
+    }, [versionPersistence]);
     return [state, api];
 }
 const Context = createContext(null);

package/lib/utils/docsPreferredVersion/useDocsPreferredVersion.d.ts

@@ -1,5 +1,7 @@
+/// <reference types="@docusaurus/plugin-content-docs" />
+import { GlobalVersion } from '@theme/hooks/useDocs';
 export declare function useDocsPreferredVersion(pluginId?: string | undefined): {
-    readonly preferredVersion: any;
-    readonly savePreferredVersionName: (versionName: string) => void;
+    preferredVersion: GlobalVersion | null | undefined;
+    savePreferredVersionName: (versionName: string) => void;
 };
-export declare function useDocsPreferredVersionByPluginId(): Record<string, any>;
+export declare function useDocsPreferredVersionByPluginId(): Record<string, GlobalVersion | null | undefined>;

package/lib/utils/docsPreferredVersion/useDocsPreferredVersion.js

@@ -8,7 +8,6 @@ import { useCallback } from 'react';
 import { useDocsPreferredVersionContext } from './DocsPreferredVersionProvider';
 import { useAllDocsData, useDocsData } from '@theme/hooks/useDocs';
 import { DEFAULT_PLUGIN_ID } from '@docusaurus/constants';
-// TODO improve typing
 // Note, the preferredVersion attribute will always be null before mount
 export function useDocsPreferredVersion(pluginId = DEFAULT_PLUGIN_ID) {
     const docsData = useDocsData(pluginId);
@@ -19,7 +18,7 @@ export function useDocsPreferredVersion(pluginId = DEFAULT_PLUGIN_ID) {
         : null;
     const savePreferredVersionName = useCallback((versionName) => {
         api.savePreferredVersion(pluginId, versionName);
-    }, [api]);
+    }, [api, pluginId]);
     return { preferredVersion, savePreferredVersionName };
 }
 export function useDocsPreferredVersionByPluginId() {

package/lib/utils/generalUtils.js

@@ -6,8 +6,8 @@
  */
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 export const useTitleFormatter = (title) => {
-    const { siteConfig = {} } = useDocusaurusContext();
-    const { title: siteTitle, titleDelimiter = '|' } = siteConfig;
+    const { siteConfig } = useDocusaurusContext();
+    const { title: siteTitle, titleDelimiter } = siteConfig;
     return title && title.trim().length
         ? `${title.trim()} ${titleDelimiter} ${siteTitle}`
         : siteTitle;

package/lib/utils/historyUtils.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 { Location, Action } from '@docusaurus/history';
+declare type HistoryBlockHandler = (location: Location, action: Action) => void | false;
+export declare function useHistoryActionHandler(handler: HistoryBlockHandler): void;
+export declare function useHistoryPopHandler(handler: HistoryBlockHandler): void;
+export {};

package/lib/utils/historyUtils.js

@@ -0,0 +1,42 @@
+/**
+ * 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 { useEffect, useRef } from 'react';
+import { useHistory } from '@docusaurus/router';
+/*
+Permits to register a handler that will be called on history actions (pop,push,replace)
+If the handler returns false, the navigation transition will be blocked/cancelled
+ */
+export function useHistoryActionHandler(handler) {
+    const { block } = useHistory();
+    // Avoid stale closure issues without triggering useless re-renders
+    const lastHandlerRef = useRef(handler);
+    useEffect(() => {
+        lastHandlerRef.current = handler;
+    }, [handler]);
+    useEffect(() => {
+        // See https://github.com/remix-run/history/blob/main/docs/blocking-transitions.md
+        return block((location, action) => {
+            return lastHandlerRef.current(location, action);
+        });
+    }, [block, lastHandlerRef]);
+}
+/*
+Permits to register a handler that will be called on history pop navigation (backward/forward)
+If the handler returns false, the backward/forward transition will be blocked
+
+Unfortunately there's no good way to detect the "direction" (backward/forward) of the POP event.
+ */
+export function useHistoryPopHandler(handler) {
+    useHistoryActionHandler((location, action) => {
+        if (action === 'POP') {
+            // Eventually block navigation if handler returns false
+            return handler(location, action);
+        }
+        // Don't block other navigation actions
+        return undefined;
+    });
+}

package/lib/utils/jsUtils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+/**
+ * Gets the duplicate values in an array.
+ * @param arr The array.
+ * @param comparator Compares two values and returns `true` if they are equal (duplicated).
+ * @returns Value of the elements `v` that have a preceding element `u` where `comparator(u, v) === true`. Values within the returned array are not guaranteed to be unique.
+ */
+export declare function duplicates<T>(arr: readonly T[], comparator?: (a: T, b: T) => boolean): T[];

package/lib/utils/jsUtils.js

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+// A replacement of lodash in client code
+/**
+ * Gets the duplicate values in an array.
+ * @param arr The array.
+ * @param comparator Compares two values and returns `true` if they are equal (duplicated).
+ * @returns Value of the elements `v` that have a preceding element `u` where `comparator(u, v) === true`. Values within the returned array are not guaranteed to be unique.
+ */
+export function duplicates(arr, comparator = (a, b) => a === b) {
+    return arr.filter((v, vIndex) => arr.findIndex((u) => comparator(u, v)) !== vIndex);
+}

package/lib/utils/mobileSecondaryMenu.js

@@ -32,6 +32,7 @@ export function useMobileSecondaryMenuRenderer() {
 function useShallowMemoizedObject(obj) {
     return useMemo(() => obj, 
     // Is this safe?
+    // eslint-disable-next-line react-hooks/exhaustive-deps
     [...Object.keys(obj), ...Object.values(obj)]);
 }
 // Fill the secondary menu placeholder with some real content

package/lib/utils/reactUtils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { useLayoutEffect } from 'react';
+export declare const useIsomorphicLayoutEffect: typeof useLayoutEffect;
+export declare function useDynamicCallback<T extends (...args: never[]) => unknown>(callback: T): T;

package/lib/utils/reactUtils.js

@@ -0,0 +1,26 @@
+/**
+ * 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 { 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)
+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
+export function useDynamicCallback(callback) {
+    const ref = useRef(callback);
+    useIsomorphicLayoutEffect(() => {
+        ref.current = callback;
+    }, [callback]);
+    // @ts-expect-error: TODO, not sure how to fix this TS error
+    return useCallback((...args) => ref.current(...args), []);
+}

package/lib/utils/regexpUtils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+/**
+ * Utility to convert an optional string into a Regex case sensitive and global
+ */
+export declare function isRegexpStringMatch(regexAsString?: string, valueToTest?: string): boolean;

package/lib/utils/regexpUtils.js

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+/**
+ * Utility to convert an optional string into a Regex case sensitive and global
+ */
+export function isRegexpStringMatch(regexAsString, valueToTest) {
+    if (typeof regexAsString === 'undefined' ||
+        typeof valueToTest === 'undefined') {
+        return false;
+    }
+    return new RegExp(regexAsString, 'gi').test(valueToTest);
+}

package/lib/utils/scrollUtils.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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, { 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
+     */
+    scrollEventsEnabledRef: React.MutableRefObject<boolean>;
+    /**
+     * Enables scroll events in `useScrollPosition`
+     */
+    enableScrollEvents: () => void;
+    /**
+     * Disables scroll events in `useScrollPosition`
+     */
+    disableScrollEvents: () => void;
+};
+export declare function ScrollControllerProvider({ children, }: {
+    children: ReactNode;
+}): JSX.Element;
+export declare function useScrollController(): ScrollController;
+declare type ScrollPosition = {
+    scrollX: number;
+    scrollY: number;
+};
+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
+ * 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
+ *
+ * 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
+ */
+export declare function useScrollPositionBlocker(): UseScrollPositionBlockerReturn;
+export {};

package/lib/utils/scrollUtils.js

@@ -0,0 +1,137 @@
+/**
+ * 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, { createContext, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, } from 'react';
+import { useDynamicCallback } from './reactUtils';
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+function useScrollControllerContextValue() {
+    const scrollEventsEnabledRef = useRef(true);
+    return useMemo(() => ({
+        scrollEventsEnabledRef,
+        enableScrollEvents: () => {
+            scrollEventsEnabledRef.current = true;
+        },
+        disableScrollEvents: () => {
+            scrollEventsEnabledRef.current = false;
+        },
+    }), []);
+}
+const ScrollMonitorContext = createContext(undefined);
+export function ScrollControllerProvider({ children, }) {
+    return (React.createElement(ScrollMonitorContext.Provider, { value: useScrollControllerContextValue() }, children));
+}
+export function useScrollController() {
+    const context = useContext(ScrollMonitorContext);
+    if (context == null) {
+        throw new Error('"useScrollController" is used but no context provider was found in the React tree.');
+    }
+    return context;
+}
+const getScrollPosition = () => {
+    return ExecutionEnvironment.canUseDOM
+        ? {
+            scrollX: window.pageXOffset,
+            scrollY: window.pageYOffset,
+        }
+        : null;
+};
+export function useScrollPosition(effect, deps = []) {
+    const { scrollEventsEnabledRef } = useScrollController();
+    const lastPositionRef = useRef(getScrollPosition());
+    const dynamicEffect = useDynamicCallback(effect);
+    useEffect(() => {
+        const handleScroll = () => {
+            if (!scrollEventsEnabledRef.current) {
+                return;
+            }
+            const currentPosition = getScrollPosition();
+            if (dynamicEffect) {
+                dynamicEffect(currentPosition, lastPositionRef.current);
+            }
+            lastPositionRef.current = currentPosition;
+        };
+        const opts = {
+            passive: true,
+        };
+        handleScroll();
+        window.addEventListener('scroll', handleScroll, opts);
+        return () => window.removeEventListener('scroll', handleScroll, opts);
+    }, [
+        dynamicEffect,
+        scrollEventsEnabledRef,
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        ...deps,
+    ]);
+}
+function useScrollPositionSaver() {
+    const lastElementRef = useRef({
+        elem: null,
+        top: 0,
+    });
+    const save = useCallback((elem) => {
+        lastElementRef.current = {
+            elem,
+            top: elem.getBoundingClientRect().top,
+        };
+    }, []);
+    const restore = useCallback(() => {
+        const { current: { elem, top }, } = lastElementRef;
+        if (!elem) {
+            return { restored: false };
+        }
+        const newTop = elem.getBoundingClientRect().top;
+        const heightDiff = newTop - top;
+        if (heightDiff) {
+            window.scrollBy({ left: 0, top: heightDiff });
+        }
+        lastElementRef.current = { elem: null, top: 0 };
+        return { restored: heightDiff !== 0 };
+    }, []);
+    return useMemo(() => ({ save, restore }), [restore, save]);
+}
+/**
+ * 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
+ *
+ * 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
+ */
+export function useScrollPositionBlocker() {
+    const scrollController = useScrollController();
+    const scrollPositionSaver = useScrollPositionSaver();
+    const nextLayoutEffectCallbackRef = useRef(undefined);
+    const blockElementScrollPositionUntilNextRender = useCallback((el) => {
+        scrollPositionSaver.save(el);
+        scrollController.disableScrollEvents();
+        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
+            if (restored) {
+                const handleScrollRestoreEvent = () => {
+                    scrollController.enableScrollEvents();
+                    window.removeEventListener('scroll', handleScrollRestoreEvent);
+                };
+                window.addEventListener('scroll', handleScrollRestoreEvent);
+            }
+            else {
+                scrollController.enableScrollEvents();
+            }
+        };
+    }, [scrollController, scrollPositionSaver]);
+    useLayoutEffect(() => {
+        var _a;
+        (_a = nextLayoutEffectCallbackRef.current) === null || _a === void 0 ? void 0 : _a.call(nextLayoutEffectCallbackRef);
+    });
+    return {
+        blockElementScrollPositionUntilNextRender,
+    };
+}

package/lib/utils/tagsUtils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+export declare const translateTagsPageTitle: () => string;
+declare type TagsListItem = Readonly<{
+    name: string;
+    permalink: string;
+    count: number;
+}>;
+export declare type TagLetterEntry = Readonly<{
+    letter: string;
+    tags: TagsListItem[];
+}>;
+export declare function listTagsByLetters(tags: readonly TagsListItem[]): TagLetterEntry[];
+export {};

package/lib/utils/tagsUtils.js

@@ -0,0 +1,33 @@
+/**
+ * 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';
+export const translateTagsPageTitle = () => translate({
+    id: 'theme.tags.tagsPageTitle',
+    message: 'Tags',
+    description: 'The title of the tag list page',
+});
+function getTagLetter(tag) {
+    return tag[0].toUpperCase();
+}
+export function listTagsByLetters(tags) {
+    // Group by letters
+    const groups = {};
+    Object.values(tags).forEach((tag) => {
+        var _a;
+        const letter = getTagLetter(tag.name);
+        groups[letter] = (_a = groups[letter]) !== null && _a !== void 0 ? _a : [];
+        groups[letter].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.name.localeCompare(tag2.name));
+        return { letter, tags: sortedTags };
+    }));
+}

package/lib/utils/tocUtils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { TOCItem } from '@docusaurus/types';
+declare type FilterTOCParam = {
+    toc: readonly TOCItem[];
+    minHeadingLevel: number;
+    maxHeadingLevel: number;
+};
+export declare function filterTOC({ toc, minHeadingLevel, maxHeadingLevel, }: FilterTOCParam): TOCItem[];
+export declare function useTOCFilter({ toc, minHeadingLevel, maxHeadingLevel, }: FilterTOCParam): readonly TOCItem[];
+export {};

package/lib/utils/tocUtils.js

@@ -0,0 +1,36 @@
+/**
+ * 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';
+export function filterTOC({ toc, minHeadingLevel, maxHeadingLevel, }) {
+    function isValid(item) {
+        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,
+                },
+            ];
+        }
+        else {
+            return filteredChildren;
+        }
+    });
+}
+// Memoize potentially expensive filtering logic
+export function useTOCFilter({ toc, minHeadingLevel, maxHeadingLevel, }) {
+    return useMemo(() => {
+        return filterTOC({ toc, minHeadingLevel, maxHeadingLevel });
+    }, [toc, minHeadingLevel, maxHeadingLevel]);
+}

package/lib/utils/useLocationChange.js

@@ -4,22 +4,18 @@
  * This source code is licensed under the MIT license found in the
  * 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 { usePrevious } from './usePrevious';
+import { useDynamicCallback } from './reactUtils';
 export function useLocationChange(onLocationChange) {
     const location = useLocation();
     const previousLocation = usePrevious(location);
-    const isFirst = useRef(true);
+    const onLocationChangeDynamic = useDynamicCallback(onLocationChange);
     useEffect(() => {
-        // Prevent first effect to trigger the listener on mount
-        if (isFirst.current) {
-            isFirst.current = false;
-            return;
-        }
-        onLocationChange({
+        onLocationChangeDynamic({
             location,
             previousLocation,
         });
-    }, [location]);
+    }, [onLocationChangeDynamic, location, previousLocation]);
 }

package/lib/utils/usePrevious.js

@@ -4,10 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { useRef, useEffect } from 'react';
+import { useRef } from 'react';
+import { useIsomorphicLayoutEffect } from './reactUtils';
 export function usePrevious(value) {
     const ref = useRef();
-    useEffect(() => {
+    useIsomorphicLayoutEffect(() => {
         ref.current = value;
     });
     return ref.current;