@docusaurus/theme-common 2.0.0-beta.1 → 2.0.0-beta.10

package/lib/components/Details/index.js

@@ -0,0 +1,64 @@
+/**
+ * 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, { useRef, useState } from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import clsx from 'clsx';
+import { useCollapsible, Collapsible } from '../Collapsible';
+import styles from './styles.module.css';
+function isInSummary(node) {
+    if (!node) {
+        return false;
+    }
+    return node.tagName === 'SUMMARY' || isInSummary(node.parentElement);
+}
+function hasParent(node, parent) {
+    if (!node) {
+        return false;
+    }
+    return node === parent || hasParent(node.parentElement, parent);
+}
+function Details({ summary, children, ...props }) {
+    const isBrowser = useIsBrowser();
+    const detailsRef = useRef(null);
+    const { collapsed, setCollapsed } = useCollapsible({
+        initialState: !props.open,
+    });
+    // We use a separate prop because it must be set only after animation completes
+    // Otherwise close anim won't work
+    const [open, setOpen] = useState(props.open);
+    return (React.createElement("details", { ...props, ref: detailsRef, open: open, "data-collapsed": collapsed, className: clsx(styles.details, { [styles.isBrowser]: isBrowser }, props.className), onMouseDown: (e) => {
+            const target = e.target;
+            // Prevent a double-click to highlight summary text
+            if (isInSummary(target) && e.detail > 1) {
+                e.preventDefault();
+            }
+        }, onClick: (e) => {
+            e.stopPropagation(); // For isolation of multiple nested details/summary
+            const target = e.target;
+            const shouldToggle = isInSummary(target) && hasParent(target, detailsRef.current);
+            if (!shouldToggle) {
+                return;
+            }
+            e.preventDefault();
+            if (collapsed) {
+                setCollapsed(false);
+                setOpen(true);
+            }
+            else {
+                setCollapsed(true);
+                // setOpen(false); // Don't do this, it breaks close animation!
+            }
+        } },
+        summary,
+        React.createElement(Collapsible, { lazy: false, collapsed: collapsed, disableSSRStyle // Allows component to work fine even with JS disabled!
+            : true, onCollapseTransitionEnd: (newCollapsed) => {
+                setCollapsed(newCollapsed);
+                setOpen(!newCollapsed);
+            } },
+            React.createElement("div", { className: styles.collapsibleContent }, children))));
+}
+export default Details;

package/lib/components/Details/styles.module.css

@@ -0,0 +1,58 @@
+/**
+ * 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.
+ */
+
+/*
+CSS variables, meant to be overriden by final theme
+ */
+.details {
+  --docusaurus-details-summary-arrow-size: 0.38rem;
+  --docusaurus-details-transition: transform 200ms ease;
+  --docusaurus-details-decoration-color: grey;
+}
+
+.details > summary {
+  position: relative;
+  cursor: pointer;
+  list-style: none;
+  padding-left: 1rem;
+}
+
+/* TODO: deprecation, need to remove this after Safari will support `::marker` */
+.details > summary::-webkit-details-marker {
+  display: none;
+}
+
+.details > summary:before {
+  position: absolute;
+  top: 0.45rem;
+  left: 0;
+
+  /* CSS-only Arrow */
+  content: '';
+  border-width: var(--docusaurus-details-summary-arrow-size);
+  border-style: solid;
+  border-color: transparent transparent transparent
+    var(--docusaurus-details-decoration-color);
+
+  /* Arrow rotation anim */
+  transform: rotate(0deg);
+  transition: var(--docusaurus-details-transition);
+  transform-origin: calc(var(--docusaurus-details-summary-arrow-size) / 2) 50%;
+}
+
+/* When JS disabled/failed to load: we use the open property for arrow animation: */
+.details[open]:not(.isBrowser) > summary:before,
+/* When JS works: we use the data-attribute for arrow animation */
+.details[data-collapsed='false'].isBrowser > summary:before {
+  transform: rotate(90deg);
+}
+
+.collapsibleContent {
+  margin-top: 1rem;
+  border-top: 1px solid var(--docusaurus-details-decoration-color);
+  padding-top: 1rem;
+}

package/lib/index.d.ts

@@ -5,16 +5,36 @@
  * LICENSE file in the root directory of this source tree.
  */
 export { useThemeConfig } from './utils/useThemeConfig';
-export type { ThemeConfig, Navbar, NavbarItem, NavbarLogo, Footer, FooterLinks, FooterLinkItem, } from './utils/useThemeConfig';
+export type { ThemeConfig, UserThemeConfig, Navbar, NavbarItem, NavbarLogo, Footer, FooterLinks, FooterLinkItem, ColorModeConfig, } from './utils/useThemeConfig';
 export { createStorageSlot, listStorageKeys } from './utils/storageUtils';
 export { useAlternatePageUtils } from './utils/useAlternatePageUtils';
-export { parseCodeBlockTitle } from './utils/codeBlockUtils';
+export { useContextualSearchFilters } from './utils/useContextualSearchFilters';
+export { parseCodeBlockTitle, parseLanguage, parseLines, } from './utils/codeBlockUtils';
 export { docVersionSearchTag, DEFAULT_SEARCH_TAG } from './utils/searchUtils';
-export { isDocsPluginEnabled } from './utils/docsUtils';
+export { isDocsPluginEnabled, DocsVersionProvider, useDocsVersion, useDocById, DocsSidebarProvider, useDocsSidebar, findSidebarCategory, findFirstCategoryLink, useCurrentSidebarCategory, isActiveSidebarItem, } from './utils/docsUtils';
 export { isSamePath } from './utils/pathUtils';
 export { useTitleFormatter } from './utils/generalUtils';
 export { usePluralForm } from './utils/usePluralForm';
-export { useChangeRoute } from './utils/useChangeRoute';
+export { useLocationChange } from './utils/useLocationChange';
+export { usePrevious } from './utils/usePrevious';
+export { useCollapsible, Collapsible } from './components/Collapsible';
+export type { UseCollapsibleConfig, UseCollapsibleReturns, } from './components/Collapsible';
+export { default as Details } from './components/Details';
+export type { DetailsProps } from './components/Details';
+export { MobileSecondaryMenuProvider, MobileSecondaryMenuFiller, useMobileSecondaryMenuRenderer, } from './utils/mobileSecondaryMenu';
+export type { MobileSecondaryMenuComponent } from './utils/mobileSecondaryMenu';
 export { useDocsPreferredVersion, useDocsPreferredVersionByPluginId, } from './utils/docsPreferredVersion/useDocsPreferredVersion';
+export { duplicates, uniq } from './utils/jsUtils';
 export { DocsPreferredVersionContextProvider } from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 export { ThemeClassNames } from './utils/ThemeClassNames';
+export { AnnouncementBarProvider, useAnnouncementBar, } from './utils/announcementBarUtils';
+export { useLocalPathname } from './utils/useLocalPathname';
+export { translateTagsPageTitle, listTagsByLetters } from './utils/tagsUtils';
+export type { TagLetterEntry } from './utils/tagsUtils';
+export { useHistoryPopHandler } from './utils/historyUtils';
+export { default as useTOCHighlight } from './utils/useTOCHighlight';
+export type { TOCHighlightConfig } from './utils/useTOCHighlight';
+export { useTOCFilter } from './utils/tocUtils';
+export { ScrollControllerProvider, useScrollController, useScrollPosition, useScrollPositionBlocker, } from './utils/scrollUtils';
+export { useIsomorphicLayoutEffect, useDynamicCallback, } from './utils/reactUtils';
+export { isRegexpStringMatch } from './utils/regexpUtils';

package/lib/index.js

@@ -7,13 +7,28 @@
 export { useThemeConfig } from './utils/useThemeConfig';
 export { createStorageSlot, listStorageKeys } from './utils/storageUtils';
 export { useAlternatePageUtils } from './utils/useAlternatePageUtils';
-export { parseCodeBlockTitle } from './utils/codeBlockUtils';
+export { useContextualSearchFilters } from './utils/useContextualSearchFilters';
+export { parseCodeBlockTitle, parseLanguage, parseLines, } from './utils/codeBlockUtils';
 export { docVersionSearchTag, DEFAULT_SEARCH_TAG } from './utils/searchUtils';
-export { isDocsPluginEnabled } from './utils/docsUtils';
+export { isDocsPluginEnabled, DocsVersionProvider, useDocsVersion, useDocById, DocsSidebarProvider, useDocsSidebar, findSidebarCategory, findFirstCategoryLink, useCurrentSidebarCategory, isActiveSidebarItem, } from './utils/docsUtils';
 export { isSamePath } from './utils/pathUtils';
 export { useTitleFormatter } from './utils/generalUtils';
 export { usePluralForm } from './utils/usePluralForm';
-export { useChangeRoute } from './utils/useChangeRoute';
+export { useLocationChange } from './utils/useLocationChange';
+export { usePrevious } from './utils/usePrevious';
+export { useCollapsible, Collapsible } from './components/Collapsible';
+export { default as Details } from './components/Details';
+export { MobileSecondaryMenuProvider, MobileSecondaryMenuFiller, useMobileSecondaryMenuRenderer, } from './utils/mobileSecondaryMenu';
 export { useDocsPreferredVersion, useDocsPreferredVersionByPluginId, } from './utils/docsPreferredVersion/useDocsPreferredVersion';
+export { duplicates, uniq } from './utils/jsUtils';
 export { DocsPreferredVersionContextProvider } from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 export { ThemeClassNames } from './utils/ThemeClassNames';
+export { AnnouncementBarProvider, useAnnouncementBar, } from './utils/announcementBarUtils';
+export { useLocalPathname } from './utils/useLocalPathname';
+export { translateTagsPageTitle, listTagsByLetters } from './utils/tagsUtils';
+export { useHistoryPopHandler } from './utils/historyUtils';
+export { default as useTOCHighlight } from './utils/useTOCHighlight';
+export { useTOCFilter } from './utils/tocUtils';
+export { ScrollControllerProvider, useScrollController, useScrollPosition, useScrollPositionBlocker, } from './utils/scrollUtils';
+export { useIsomorphicLayoutEffect, useDynamicCallback, } from './utils/reactUtils';
+export { isRegexpStringMatch } from './utils/regexpUtils';

package/lib/utils/ThemeClassNames.d.ts

@@ -5,18 +5,42 @@
  * LICENSE file in the root directory of this source tree.
  */
 export declare const ThemeClassNames: {
-    page: {
-        blogListPage: string;
-        blogPostPage: string;
-        blogTagsListPage: string;
-        blogTagsPostPage: string;
-        docPage: string;
-        mdxPage: string;
+    readonly page: {
+        readonly blogListPage: "blog-list-page";
+        readonly blogPostPage: "blog-post-page";
+        readonly blogTagsListPage: "blog-tags-list-page";
+        readonly blogTagPostListPage: "blog-tags-post-list-page";
+        readonly docsDocPage: "docs-doc-page";
+        readonly docsTagsListPage: "docs-tags-list-page";
+        readonly docsTagDocListPage: "docs-tags-doc-list-page";
+        readonly mdxPage: "mdx-page";
     };
-    wrapper: {
-        main: string;
-        blogPages: string;
-        docPages: string;
-        mdxPages: string;
+    readonly wrapper: {
+        readonly main: "main-wrapper";
+        readonly blogPages: "blog-wrapper";
+        readonly docsPages: "docs-wrapper";
+        readonly mdxPages: "mdx-wrapper";
     };
+    readonly common: {
+        readonly editThisPage: "theme-edit-this-page";
+        readonly lastUpdated: "theme-last-updated";
+        readonly backToTopButton: "theme-back-to-top-button";
+    };
+    readonly layout: {};
+    readonly docs: {
+        readonly docVersionBanner: "theme-doc-version-banner";
+        readonly docVersionBadge: "theme-doc-version-badge";
+        readonly docMarkdown: "theme-doc-markdown";
+        readonly docTocMobile: "theme-doc-toc-mobile";
+        readonly docTocDesktop: "theme-doc-toc-desktop";
+        readonly docFooter: "theme-doc-footer";
+        readonly docFooterTagsRow: "theme-doc-footer-tags-row";
+        readonly docFooterEditMetaRow: "theme-doc-footer-edit-meta-row";
+        readonly docSidebarMenu: "theme-doc-sidebar-menu";
+        readonly docSidebarItemCategory: "theme-doc-sidebar-item-category";
+        readonly docSidebarItemLink: "theme-doc-sidebar-item-link";
+        readonly docSidebarItemCategoryLevel: (level: number) => `theme-doc-sidebar-item-category-level-${number}`;
+        readonly docSidebarItemLinkLevel: (level: number) => `theme-doc-sidebar-item-link-level-${number}`;
+    };
+    readonly blog: {};
 };

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

@@ -0,0 +1,17 @@
+/**
+ * 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 { ReactNode } from 'react';
+export declare const AnnouncementBarDismissStorageKey = "docusaurus.announcement.dismiss";
+declare type AnnouncementBarAPI = {
+    readonly isActive: boolean;
+    readonly close: () => void;
+};
+export declare function AnnouncementBarProvider({ children, }: {
+    children: ReactNode;
+}): JSX.Element;
+export declare const useAnnouncementBar: () => AnnouncementBarAPI;
+export {};

package/lib/utils/announcementBarUtils.js

@@ -0,0 +1,69 @@
+/**
+ * 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, { useState, useEffect, useCallback, useMemo, useContext, createContext, } from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
+import { createStorageSlot } from './storageUtils';
+import { useThemeConfig } from './useThemeConfig';
+export const AnnouncementBarDismissStorageKey = 'docusaurus.announcement.dismiss';
+const AnnouncementBarIdStorageKey = 'docusaurus.announcement.id';
+const AnnouncementBarDismissStorage = createStorageSlot(AnnouncementBarDismissStorageKey);
+const IdStorage = createStorageSlot(AnnouncementBarIdStorageKey);
+const isDismissedInStorage = () => AnnouncementBarDismissStorage.get() === 'true';
+const setDismissedInStorage = (bool) => AnnouncementBarDismissStorage.set(String(bool));
+const useAnnouncementBarContextValue = () => {
+    const { announcementBar } = useThemeConfig();
+    const isBrowser = useIsBrowser();
+    const [isClosed, setClosed] = useState(() => 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)
+            false);
+    // Update state after hydration
+    useEffect(() => {
+        setClosed(isDismissedInStorage());
+    }, []);
+    const handleClose = useCallback(() => {
+        setDismissedInStorage(true);
+        setClosed(true);
+    }, []);
+    useEffect(() => {
+        if (!announcementBar) {
+            return;
+        }
+        const { id } = announcementBar;
+        let viewedId = IdStorage.get();
+        // retrocompatibility due to spelling mistake of default id
+        // see https://github.com/facebook/docusaurus/issues/3338
+        if (viewedId === 'annoucement-bar') {
+            viewedId = 'announcement-bar';
+        }
+        const isNewAnnouncement = id !== viewedId;
+        IdStorage.set(id);
+        if (isNewAnnouncement) {
+            setDismissedInStorage(false);
+        }
+        if (isNewAnnouncement || !isDismissedInStorage()) {
+            setClosed(false);
+        }
+    }, [announcementBar]);
+    return useMemo(() => ({
+        isActive: !!announcementBar && !isClosed,
+        close: handleClose,
+    }), [announcementBar, isClosed, handleClose]);
+};
+const AnnouncementBarContext = createContext(null);
+export function AnnouncementBarProvider({ children, }) {
+    const value = useAnnouncementBarContextValue();
+    return (React.createElement(AnnouncementBarContext.Provider, { value: value }, children));
+}
+export const useAnnouncementBar = () => {
+    const api = useContext(AnnouncementBarContext);
+    if (!api) {
+        throw new Error('useAnnouncementBar(): AnnouncementBar not found in React context: make sure to use the AnnouncementBarProvider on top of the tree');
+    }
+    return api;
+};

package/lib/utils/codeBlockUtils.d.ts

@@ -4,4 +4,14 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { Language } from 'prism-react-renderer';
 export declare function parseCodeBlockTitle(metastring?: string): string;
+export declare function parseLanguage(className?: string): Language | undefined;
+/**
+ * @param metastring The highlight range declared here starts at 1
+ * @returns Note: all line numbers start at 0, not 1
+ */
+export declare function parseLines(content: string, metastring?: string, language?: Language): {
+    highlightLines: number[];
+    code: string;
+};

package/lib/utils/codeBlockUtils.js

@@ -4,8 +4,127 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import rangeParser from 'parse-numeric-range';
 const codeBlockTitleRegex = /title=(["'])(.*?)\1/;
+const highlightLinesRangeRegex = /{([\d,-]+)}/;
+const commentTypes = ['js', 'jsBlock', 'jsx', 'python', 'html'];
+// Supported types of highlight comments
+const commentPatterns = {
+    js: {
+        start: '\\/\\/',
+        end: '',
+    },
+    jsBlock: {
+        start: '\\/\\*',
+        end: '\\*\\/',
+    },
+    jsx: {
+        start: '\\{\\s*\\/\\*',
+        end: '\\*\\/\\s*\\}',
+    },
+    python: {
+        start: '#',
+        end: '',
+    },
+    html: {
+        start: '<!--',
+        end: '-->',
+    },
+};
+const magicCommentDirectives = [
+    'highlight-next-line',
+    'highlight-start',
+    'highlight-end',
+];
+const getMagicCommentDirectiveRegex = (languages = commentTypes) => {
+    // to be more reliable, the opening and closing comment must match
+    const commentPattern = languages
+        .map((lang) => {
+        const { start, end } = commentPatterns[lang];
+        return `(?:${start}\\s*(${magicCommentDirectives.join('|')})\\s*${end})`;
+    })
+        .join('|');
+    // white space is allowed, but otherwise it should be on it's own line
+    return new RegExp(`^\\s*(?:${commentPattern})\\s*$`);
+};
+// select comment styles based on language
+const magicCommentDirectiveRegex = (lang) => {
+    switch (lang) {
+        case 'js':
+        case 'javascript':
+        case 'ts':
+        case 'typescript':
+            return getMagicCommentDirectiveRegex(['js', 'jsBlock']);
+        case 'jsx':
+        case 'tsx':
+            return getMagicCommentDirectiveRegex(['js', 'jsBlock', 'jsx']);
+        case 'html':
+            return getMagicCommentDirectiveRegex(['js', 'jsBlock', 'html']);
+        case 'python':
+        case 'py':
+            return getMagicCommentDirectiveRegex(['python']);
+        default:
+            // all comment types
+            return getMagicCommentDirectiveRegex();
+    }
+};
 export function parseCodeBlockTitle(metastring) {
     var _a, _b;
     return (_b = (_a = metastring === null || metastring === void 0 ? void 0 : metastring.match(codeBlockTitleRegex)) === null || _a === void 0 ? void 0 : _a[2]) !== null && _b !== void 0 ? _b : '';
 }
+export function parseLanguage(className) {
+    const languageClassName = className === null || className === void 0 ? void 0 : className.split(' ').find((str) => str.startsWith('language-'));
+    return languageClassName === null || languageClassName === void 0 ? void 0 : languageClassName.replace(/language-/, '');
+}
+/**
+ * @param metastring The highlight range declared here starts at 1
+ * @returns Note: all line numbers start at 0, not 1
+ */
+export function parseLines(content, metastring, language) {
+    let code = content.replace(/\n$/, '');
+    // Highlighted lines specified in props: don't parse the content
+    if (metastring && highlightLinesRangeRegex.test(metastring)) {
+        const highlightLinesRange = metastring.match(highlightLinesRangeRegex)[1];
+        const highlightLines = rangeParser(highlightLinesRange)
+            .filter((n) => n > 0)
+            .map((n) => n - 1);
+        return { highlightLines, code };
+    }
+    if (language === undefined) {
+        return { highlightLines: [], code };
+    }
+    const directiveRegex = magicCommentDirectiveRegex(language);
+    // go through line by line
+    const lines = code.split('\n');
+    let highlightBlockStart;
+    let highlightRange = '';
+    // loop through lines
+    for (let lineNumber = 0; lineNumber < lines.length;) {
+        const line = lines[lineNumber];
+        const match = line.match(directiveRegex);
+        if (match !== null) {
+            const directive = match.slice(1).find((item) => item !== undefined);
+            switch (directive) {
+                case 'highlight-next-line':
+                    highlightRange += `${lineNumber},`;
+                    break;
+                case 'highlight-start':
+                    highlightBlockStart = lineNumber;
+                    break;
+                case 'highlight-end':
+                    highlightRange += `${highlightBlockStart}-${lineNumber - 1},`;
+                    break;
+                default:
+                    break;
+            }
+            lines.splice(lineNumber, 1);
+        }
+        else {
+            // lines without directives are unchanged
+            lineNumber += 1;
+        }
+    }
+    const highlightLines = rangeParser(highlightRange);
+    code = lines.join('\n');
+    return { highlightLines, code };
+}

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

@@ -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 { ReactNode } from 'react';
+/// <reference types="react" />
 declare type DocsPreferredVersionName = string | null;
 declare type DocsPreferredVersionPluginState = {
     preferredVersionName: DocsPreferredVersionName;
@@ -15,7 +15,7 @@ declare function useContextValue(): readonly [DocsPreferredVersionState, {
 }];
 declare type DocsPreferredVersionContextValue = ReturnType<typeof useContextValue>;
 export declare function DocsPreferredVersionContextProvider({ children, }: {
-    children: ReactNode;
+    children: JSX.Element;
 }): JSX.Element;
 export declare function useDocsPreferredVersionContext(): DocsPreferredVersionContextValue;
 export {};

package/lib/utils/docsPreferredVersion/DocsPreferredVersionProvider.js

@@ -69,7 +69,7 @@ function useContextValue() {
         return {
             savePreferredVersion,
         };
-    }, [setState]);
+    }, [versionPersistence]);
     return [state, api];
 }
 const Context = createContext(null);
@@ -78,7 +78,7 @@ export function DocsPreferredVersionContextProvider({ children, }) {
         return (React.createElement(DocsPreferredVersionContextProviderUnsafe, null, children));
     }
     else {
-        return React.createElement(React.Fragment, null, children);
+        return children;
     }
 }
 function DocsPreferredVersionContextProviderUnsafe({ children, }) {

package/lib/utils/docsPreferredVersion/DocsPreferredVersionStorage.js

@@ -10,9 +10,7 @@ const DocsPreferredVersionStorage = {
     save: (pluginId, persistence, versionName) => {
         createStorageSlot(storageKey(pluginId), { persistence }).set(versionName);
     },
-    read: (pluginId, persistence) => {
-        return createStorageSlot(storageKey(pluginId), { persistence }).get();
-    },
+    read: (pluginId, persistence) => createStorageSlot(storageKey(pluginId), { persistence }).get(),
     clear: (pluginId, persistence) => {
         createStorageSlot(storageKey(pluginId), { persistence }).del();
     },

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

@@ -1,5 +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.
+ */
+/// <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/docsUtils.d.ts

@@ -4,4 +4,24 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { ReactNode } from 'react';
+import { PropSidebar, PropSidebarItem, PropSidebarItemCategory, PropVersionDoc, PropVersionMetadata } from '@docusaurus/plugin-content-docs';
 export declare const isDocsPluginEnabled: boolean;
+declare const EmptyContextValue: unique symbol;
+export declare function DocsVersionProvider({ children, version, }: {
+    children: ReactNode;
+    version: PropVersionMetadata | typeof EmptyContextValue;
+}): JSX.Element;
+export declare function useDocsVersion(): PropVersionMetadata;
+export declare function useDocById(id: string): PropVersionDoc;
+export declare function useDocById(id: string | undefined): PropVersionDoc | undefined;
+export declare function DocsSidebarProvider({ children, sidebar, }: {
+    children: ReactNode;
+    sidebar: PropSidebar | null;
+}): JSX.Element;
+export declare function useDocsSidebar(): PropSidebar | null;
+export declare function findSidebarCategory(sidebar: PropSidebar, predicate: (category: PropSidebarItemCategory) => boolean): PropSidebarItemCategory | undefined;
+export declare function findFirstCategoryLink(item: PropSidebarItemCategory): string | undefined;
+export declare function useCurrentSidebarCategory(): PropSidebarItemCategory;
+export declare function isActiveSidebarItem(item: PropSidebarItem, activePath: string): boolean;
+export {};