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

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/useLocalPathname.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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 function useLocalPathname(): string;

package/lib/utils/useLocalPathname.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.
+ */
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import { useLocation } from '@docusaurus/router';
+// Get the pathname of current route, without the optional site baseUrl
+// - /docs/myDoc => /docs/myDoc
+// - /baseUrl/docs/myDoc => /docs/myDoc
+export function useLocalPathname() {
+    const { siteConfig: { baseUrl }, } = useDocusaurusContext();
+    const { pathname } = useLocation();
+    return pathname.replace(baseUrl, '/');
+}

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;

package/lib/utils/useTOCHighlight.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 type TOCHighlightConfig = {
+    linkClassName: string;
+    linkActiveClassName: string;
+    minHeadingLevel: number;
+    maxHeadingLevel: number;
+};
+declare function useTOCHighlight(config: TOCHighlightConfig | undefined): void;
+export default useTOCHighlight;

package/lib/utils/useTOCHighlight.js

@@ -0,0 +1,124 @@
+/**
+ * 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 { useThemeConfig } from './useThemeConfig';
+/*
+TODO make the hardcoded theme-classic classnames configurable
+(or add them to ThemeClassNames?)
+ */
+// If the anchor has no height and is just a "marker" in the dom; we'll use the parent (normally the link text) rect boundaries instead
+function getVisibleBoundingClientRect(element) {
+    const rect = element.getBoundingClientRect();
+    const hasNoHeight = rect.top === rect.bottom;
+    if (hasNoHeight) {
+        return getVisibleBoundingClientRect(element.parentNode);
+    }
+    return rect;
+}
+// Considering we divide viewport into 2 zones of each 50vh
+// This returns true if an element is in the first zone (ie, appear in viewport, near the top)
+function isInViewportTopHalf(boundingRect) {
+    return boundingRect.top > 0 && boundingRect.bottom < window.innerHeight / 2;
+}
+function getAnchors({ minHeadingLevel, maxHeadingLevel, }) {
+    const selectors = [];
+    for (let i = minHeadingLevel; i <= maxHeadingLevel; i += 1) {
+        selectors.push(`h${i}.anchor`);
+    }
+    return Array.from(document.querySelectorAll(selectors.join()));
+}
+function getActiveAnchor(anchors, { anchorTopOffset, }) {
+    var _a;
+    // Naming is hard
+    // The "nextVisibleAnchor" is the first anchor that appear under the viewport top boundary
+    // Note: it does not mean this anchor is visible yet, but if user continues scrolling down, it will be the first to become visible
+    const nextVisibleAnchor = anchors.find((anchor) => {
+        const boundingRect = getVisibleBoundingClientRect(anchor);
+        return boundingRect.top >= anchorTopOffset;
+    });
+    if (nextVisibleAnchor) {
+        const boundingRect = getVisibleBoundingClientRect(nextVisibleAnchor);
+        // If anchor is in the top half of the viewport: it is the one we consider "active"
+        // (unless it's too close to the top and and soon to be scrolled outside viewport)
+        if (isInViewportTopHalf(boundingRect)) {
+            return nextVisibleAnchor;
+        }
+        // If anchor is in the bottom half of the viewport, or under the viewport, we consider the active anchor is the previous one
+        // This is because the main text appearing in the user screen mostly belong to the previous anchor
+        else {
+            // Returns null for the first anchor, see https://github.com/facebook/docusaurus/issues/5318
+            return (_a = anchors[anchors.indexOf(nextVisibleAnchor) - 1]) !== null && _a !== void 0 ? _a : null;
+        }
+    }
+    // no anchor under viewport top? (ie we are at the bottom of the page)
+    // => highlight the last anchor found
+    else {
+        return anchors[anchors.length - 1];
+    }
+}
+function getLinkAnchorValue(link) {
+    return decodeURIComponent(link.href.substring(link.href.indexOf('#') + 1));
+}
+function getLinks(linkClassName) {
+    return Array.from(document.getElementsByClassName(linkClassName));
+}
+function getNavbarHeight() {
+    // Not ideal to obtain actual height this way
+    // Using TS ! (not ?) because otherwise a bad selector would be un-noticed
+    return document.querySelector('.navbar').clientHeight;
+}
+function useAnchorTopOffsetRef() {
+    const anchorTopOffsetRef = useRef(0);
+    const { navbar: { hideOnScroll }, } = useThemeConfig();
+    useEffect(() => {
+        anchorTopOffsetRef.current = hideOnScroll ? 0 : getNavbarHeight();
+    }, [hideOnScroll]);
+    return anchorTopOffsetRef;
+}
+function useTOCHighlight(config) {
+    const lastActiveLinkRef = useRef(undefined);
+    const anchorTopOffsetRef = useAnchorTopOffsetRef();
+    useEffect(() => {
+        if (!config) {
+            // no-op, highlighting is disabled
+            return () => { };
+        }
+        const { linkClassName, linkActiveClassName, minHeadingLevel, maxHeadingLevel, } = config;
+        function updateLinkActiveClass(link, active) {
+            var _a;
+            if (active) {
+                if (lastActiveLinkRef.current && lastActiveLinkRef.current !== link) {
+                    (_a = lastActiveLinkRef.current) === null || _a === void 0 ? void 0 : _a.classList.remove(linkActiveClassName);
+                }
+                link.classList.add(linkActiveClassName);
+                lastActiveLinkRef.current = link;
+            }
+            else {
+                link.classList.remove(linkActiveClassName);
+            }
+        }
+        function updateActiveLink() {
+            const links = getLinks(linkClassName);
+            const anchors = getAnchors({ minHeadingLevel, maxHeadingLevel });
+            const activeAnchor = getActiveAnchor(anchors, {
+                anchorTopOffset: anchorTopOffsetRef.current,
+            });
+            const activeLink = links.find((link) => activeAnchor && activeAnchor.id === getLinkAnchorValue(link));
+            links.forEach((link) => {
+                updateLinkActiveClass(link, link === activeLink);
+            });
+        }
+        document.addEventListener('scroll', updateActiveLink);
+        document.addEventListener('resize', updateActiveLink);
+        updateActiveLink();
+        return () => {
+            document.removeEventListener('scroll', updateActiveLink);
+            document.removeEventListener('resize', updateActiveLink);
+        };
+    }, [config, anchorTopOffsetRef]);
+}
+export default useTOCHighlight;

package/lib/utils/useThemeConfig.d.ts

@@ -1,15 +1,18 @@
 import { PrismTheme } from 'prism-react-renderer';
 import { CSSProperties } from 'react';
+import { DeepPartial } from 'utility-types';
 export declare type DocsVersionPersistence = 'localStorage' | 'none';
 export declare type NavbarItem = {
     type?: string | undefined;
     items?: NavbarItem[];
     label?: string;
     position?: 'left' | 'right';
-};
+} & Record<string, unknown>;
 export declare type NavbarLogo = {
     src: string;
     srcDark?: string;
+    width?: string | number;
+    height?: string | number;
     href?: string;
     target?: string;
     alt?: string;
@@ -62,11 +65,17 @@ export declare type Footer = {
         alt?: string;
         src?: string;
         srcDark?: string;
+        width?: string | number;
+        height?: string | number;
         href?: string;
     };
     copyright?: string;
     links: FooterLinks[];
 };
+export declare type TableOfContents = {
+    minHeadingLevel: number;
+    maxHeadingLevel: number;
+};
 export declare type ThemeConfig = {
     docs: {
         versionPersistence: DocsVersionPersistence;
@@ -77,7 +86,10 @@ export declare type ThemeConfig = {
     prism: PrismConfig;
     footer?: Footer;
     hideableSidebar: boolean;
-    image: string;
+    image?: string;
     metadatas: Array<Record<string, string>>;
+    sidebarCollapsible: boolean;
+    tableOfContents: TableOfContents;
 };
+export declare type UserThemeConfig = DeepPartial<ThemeConfig>;
 export declare function useThemeConfig(): ThemeConfig;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@docusaurus/theme-common",
-  "version": "2.0.0-beta.8bda3b2db",
+  "version": "2.0.0-beta.9",
   "description": "Common code for Docusaurus themes.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
   "scripts": {
-    "build": "tsc",
-    "watch": "tsc --watch"
+    "build": "node copyUntypedFiles.js && tsc",
+    "watch": "node copyUntypedFiles.js && tsc --watch"
   },
   "publishConfig": {
     "access": "public"
@@ -18,15 +18,19 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.8bda3b2db",
-    "@docusaurus/plugin-content-blog": "2.0.0-beta.8bda3b2db",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.8bda3b2db",
-    "@docusaurus/plugin-content-pages": "2.0.0-beta.8bda3b2db",
-    "@docusaurus/types": "2.0.0-beta.8bda3b2db",
-    "tslib": "^2.1.0"
+    "@docusaurus/core": "2.0.0-beta.9",
+    "@docusaurus/plugin-content-blog": "2.0.0-beta.9",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.9",
+    "@docusaurus/plugin-content-pages": "2.0.0-beta.9",
+    "@docusaurus/types": "2.0.0-beta.9",
+    "clsx": "^1.1.1",
+    "fs-extra": "^10.0.0",
+    "tslib": "^2.3.1",
+    "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.8bda3b2db"
+    "@docusaurus/module-type-aliases": "2.0.0-beta.9",
+    "lodash": "^4.17.20"
   },
   "peerDependencies": {
     "prism-react-renderer": "^1.2.1",
@@ -34,7 +38,7 @@
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "11a61b194f840ae0d554849a71c0d9447ef770af"
+  "gitHead": "8a491fc29ad002f90e97f5b5fe4178ac8fa0c4d7"
 }