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

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,34 @@
+/**
+ * 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(() => filterTOC({ toc, minHeadingLevel, maxHeadingLevel }), [toc, minHeadingLevel, maxHeadingLevel]);
+}

package/lib/utils/useContextualSearchFilters.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.
+ */
+export declare type useContextualSearchFiltersReturns = {
+    locale: string;
+    tags: string[];
+};
+export declare function useContextualSearchFilters(): useContextualSearchFiltersReturns;

package/lib/utils/useContextualSearchFilters.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 { useAllDocsData, useActivePluginAndVersion } from '@theme/hooks/useDocs';
+import { useDocsPreferredVersionByPluginId } from './docsPreferredVersion/useDocsPreferredVersion';
+import { docVersionSearchTag, DEFAULT_SEARCH_TAG } from './searchUtils';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+// We may want to support multiple search engines, don't couple that to Algolia/DocSearch
+// Maybe users will want to use its own search engine solution
+export function useContextualSearchFilters() {
+    const { i18n } = useDocusaurusContext();
+    const allDocsData = useAllDocsData();
+    const activePluginAndVersion = useActivePluginAndVersion();
+    const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();
+    function getDocPluginTags(pluginId) {
+        var _a, _b;
+        const activeVersion = ((_a = activePluginAndVersion === null || activePluginAndVersion === void 0 ? void 0 : activePluginAndVersion.activePlugin) === null || _a === void 0 ? void 0 : _a.pluginId) === pluginId
+            ? activePluginAndVersion.activeVersion
+            : undefined;
+        const preferredVersion = docsPreferredVersionByPluginId[pluginId];
+        const latestVersion = allDocsData[pluginId].versions.find((v) => v.isLast);
+        const version = (_b = activeVersion !== null && activeVersion !== void 0 ? activeVersion : preferredVersion) !== null && _b !== void 0 ? _b : latestVersion;
+        return docVersionSearchTag(pluginId, version.name);
+    }
+    const tags = [
+        DEFAULT_SEARCH_TAG,
+        ...Object.keys(allDocsData).map(getDocPluginTags),
+    ];
+    return {
+        locale: i18n.currentLocale,
+        tags,
+    };
+}

package/lib/utils/{useChangeRoute.d.ts → useLocalPathname.d.ts}

@@ -4,4 +4,4 @@
  * 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 useChangeRoute(onRouteChange: () => void): void;
+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.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.
+ */
+import { Location } from '@docusaurus/history';
+declare type LocationChangeEvent = {
+    location: Location;
+    previousLocation: Location | undefined;
+};
+declare type OnLocationChange = (locationChangeEvent: LocationChangeEvent) => void;
+export declare function useLocationChange(onLocationChange: OnLocationChange): void;
+export {};

package/lib/utils/useLocationChange.js

@@ -0,0 +1,23 @@
+/**
+ * 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 } 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 onLocationChangeDynamic = useDynamicCallback(onLocationChange);
+    useEffect(() => {
+        if (location !== previousLocation) {
+            onLocationChangeDynamic({
+                location,
+                previousLocation,
+            });
+        }
+    }, [onLocationChangeDynamic, location, previousLocation]);
+}

package/lib/utils/usePluralForm.js

@@ -87,8 +87,6 @@ function selectPluralMessage(pluralMessages, count, localePluralForms) {
 export function usePluralForm() {
     const localePluralForm = useLocalePluralForms();
     return {
-        selectMessage: (count, pluralMessages) => {
-            return selectPluralMessage(pluralMessages, count, localePluralForm);
-        },
+        selectMessage: (count, pluralMessages) => selectPluralMessage(pluralMessages, count, localePluralForm),
     };
 }

package/{src/utils/docsUtils.ts → lib/utils/usePrevious.d.ts}

@@ -4,8 +4,4 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-
-import {useAllDocsData} from '@theme/hooks/useDocs';
-
-// TODO not ideal, see also "useDocs"
-export const isDocsPluginEnabled: boolean = !!useAllDocsData;
+export declare function usePrevious<T>(value: T): T | undefined;

package/lib/utils/usePrevious.js

@@ -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 { useRef } from 'react';
+import { useIsomorphicLayoutEffect } from './reactUtils';
+export function usePrevious(value) {
+    const ref = useRef();
+    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,24 @@
+/**
+ * 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 { 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 +71,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 +92,10 @@ export declare type ThemeConfig = {
     prism: PrismConfig;
     footer?: Footer;
     hideableSidebar: boolean;
-    image: string;
-    metadatas: Array<Record<string, string>>;
+    image?: string;
+    metadata: 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.1",
+  "version": "2.0.0-beta.10",
   "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,23 +18,29 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.1",
-    "@docusaurus/plugin-content-blog": "2.0.0-beta.1",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.1",
-    "@docusaurus/plugin-content-pages": "2.0.0-beta.1",
-    "@docusaurus/types": "2.0.0-beta.1",
-    "tslib": "^2.1.0"
+    "@docusaurus/plugin-content-blog": "2.0.0-beta.10",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.10",
+    "@docusaurus/plugin-content-pages": "2.0.0-beta.10",
+    "clsx": "^1.1.1",
+    "fs-extra": "^10.0.0",
+    "parse-numeric-range": "^1.3.0",
+    "tslib": "^2.3.1",
+    "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.1"
+    "@docusaurus/module-type-aliases": "2.0.0-beta.10",
+    "@docusaurus/types": "2.0.0-beta.10",
+    "@testing-library/react-hooks": "^7.0.2",
+    "lodash": "^4.17.20"
   },
   "peerDependencies": {
+    "@docusaurus/core": "2.0.0-beta.9",
     "prism-react-renderer": "^1.2.1",
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "72ed3476bf4ffe1fc2d1025dd2def536a2de8f12"
+  "gitHead": "6f4869af5721435d6995e63e2f24ac41646e34ea"
 }