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

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,8 +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,6 +1,6 @@
 {
   "name": "@docusaurus/theme-common",
-  "version": "2.0.0-beta.8e9b829d9",
+  "version": "2.0.0-beta.9",
   "description": "Common code for Docusaurus themes.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -18,17 +18,19 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/plugin-content-blog": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/plugin-content-pages": "2.0.0-beta.8e9b829d9",
-    "@docusaurus/types": "2.0.0-beta.8e9b829d9",
+    "@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.1.0"
+    "tslib": "^2.3.1",
+    "utility-types": "^3.10.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.8e9b829d9"
+    "@docusaurus/module-type-aliases": "2.0.0-beta.9",
+    "lodash": "^4.17.20"
   },
   "peerDependencies": {
     "prism-react-renderer": "^1.2.1",
@@ -36,7 +38,7 @@
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "cb79fda03ac12835068842a7e0a86f610974eae2"
+  "gitHead": "8a491fc29ad002f90e97f5b5fe4178ac8fa0c4d7"
 }

package/src/components/Collapsible/index.tsx

@@ -120,7 +120,7 @@ function useCollapseAnimation({
 
     el.style.willChange = 'height';
 
-    function startAnimation(): () => void {
+    function startAnimation() {
       const animationFrame = requestAnimationFrame(() => {
         // When collapsing
         if (collapsed) {
@@ -182,35 +182,23 @@ function CollapsibleBase({
   disableSSRStyle,
 }: CollapsibleBaseProps) {
   // any because TS is a pain for HTML element refs, see https://twitter.com/sebastienlorber/status/1412784677795110914
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   const collapsibleRef = useRef<any>(null);
 
   useCollapseAnimation({collapsibleRef, collapsed, animation});
 
   return (
     <As
-      // @ts-expect-error: see https://twitter.com/sebastienlorber/status/1412784677795110914
+      // @ts-expect-error: the "too complicated type" is produced from "CollapsibleElementType" being a huge union
       ref={collapsibleRef}
       style={disableSSRStyle ? undefined : getSSRStyle(collapsed)}
-      onTransitionEnd={(e) => {
+      onTransitionEnd={(e: React.TransitionEvent) => {
         if (e.propertyName !== 'height') {
           return;
         }
 
-        const el = collapsibleRef.current!;
-        const currentCollapsibleElementHeight = el.style.height;
-
-        if (
-          !collapsed &&
-          parseInt(currentCollapsibleElementHeight, 10) === el.scrollHeight
-        ) {
-          applyCollapsedStyle(el, false);
-          onCollapseTransitionEnd?.(false);
-        }
-
-        if (currentCollapsibleElementHeight === CollapsedStyles.height) {
-          applyCollapsedStyle(el, true);
-          onCollapseTransitionEnd?.(true);
-        }
+        applyCollapsedStyle(collapsibleRef.current!, collapsed);
+        onCollapseTransitionEnd?.(collapsed);
       }}
       className={className}>
       {children}

package/src/components/Details/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {ComponentProps, ReactElement, useRef, useState} from 'react';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import clsx from 'clsx';
 import {useCollapsible, Collapsible} from '../Collapsible';
 import styles from './styles.module.css';
@@ -30,7 +30,7 @@ export type DetailsProps = {
 } & ComponentProps<'details'>;
 
 const Details = ({summary, children, ...props}: DetailsProps): JSX.Element => {
-  const {isClient} = useDocusaurusContext();
+  const isBrowser = useIsBrowser();
   const detailsRef = useRef<HTMLDetailsElement>(null);
 
   const {collapsed, setCollapsed} = useCollapsible({
@@ -48,7 +48,7 @@ const Details = ({summary, children, ...props}: DetailsProps): JSX.Element => {
       data-collapsed={collapsed}
       className={clsx(
         styles.details,
-        {[styles.isClient]: isClient},
+        {[styles.isBrowser]: isBrowser},
         props.className,
       )}
       onMouseDown={(e) => {

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

@@ -18,9 +18,10 @@ CSS variables, meant to be overriden by final theme
   position: relative;
   cursor: pointer;
   list-style: none;
-  margin-left: 1.8rem;
+  padding-left: 1rem;
 }
 
+/* TODO: deprecation, need to remove this after Safari will support `::marker` */
 .details > summary::-webkit-details-marker {
   display: none;
 }
@@ -28,15 +29,13 @@ CSS variables, meant to be overriden by final theme
 .details > summary:before {
   position: absolute;
   top: 0.45rem;
-  left: -1.2rem;
+  left: 0;
 
   /* CSS-only Arrow */
   content: '';
-  width: 0;
-  height: 0;
-  border-top: var(--docusaurus-details-summary-arrow-size) solid transparent;
-  border-bottom: var(--docusaurus-details-summary-arrow-size) solid transparent;
-  border-left: var(--docusaurus-details-summary-arrow-size) solid
+  border-width: var(--docusaurus-details-summary-arrow-size);
+  border-style: solid;
+  border-color: transparent transparent transparent
     var(--docusaurus-details-decoration-color);
 
   /* Arrow rotation anim */
@@ -46,9 +45,9 @@ CSS variables, meant to be overriden by final theme
 }
 
 /* When JS disabled/failed to load: we use the open property for arrow animation: */
-.details[open]:not(.isClient) > summary:before,
+.details[open]:not(.isBrowser) > summary:before,
 /* When JS works: we use the data-attribute for arrow animation */
-.details[data-collapsed='false'].isClient > summary:before {
+.details[data-collapsed='false'].isBrowser > summary:before {
   transform: rotate(90deg);
 }
 

package/src/index.ts

@@ -9,6 +9,7 @@ export {useThemeConfig} from './utils/useThemeConfig';
 
 export type {
   ThemeConfig,
+  UserThemeConfig,
   Navbar,
   NavbarItem,
   NavbarLogo,
@@ -58,6 +59,8 @@ export {
   useDocsPreferredVersionByPluginId,
 } from './utils/docsPreferredVersion/useDocsPreferredVersion';
 
+export {duplicates} from './utils/jsUtils';
+
 export {DocsPreferredVersionContextProvider} from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 
 export {ThemeClassNames} from './utils/ThemeClassNames';
@@ -68,3 +71,27 @@ export {
 } 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/src/types.d.ts

@@ -5,8 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-/* eslint-disable import/no-duplicates */
-/* eslint-disable spaced-comment */
 /// <reference types="@docusaurus/module-type-aliases" />
 /// <reference types="@docusaurus/plugin-content-blog" />
 /// <reference types="@docusaurus/plugin-content-docs" />

package/src/utils/ThemeClassNames.ts

@@ -6,19 +6,57 @@
  */
 
 // 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', // List of tags
+    docsTagDocListPage: 'docs-tags-doc-list-page', // Docs for a tag
+
     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: number) =>
+      `theme-doc-sidebar-item-category-level-${level}` as const,
+    docSidebarItemLinkLevel: (level: number) =>
+      `theme-doc-sidebar-item-link-level-${level}` as const,
+    // TODO add other stable classNames here
+  },
+  blog: {
+    // TODO add other stable classNames here
+  },
+} as const;

package/src/utils/__tests__/tagUtils.test.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 {shuffle} from 'lodash';
+import {listTagsByLetters} from '../tagsUtils';
+
+describe('listTagsByLetters', () => {
+  type Param = Parameters<typeof listTagsByLetters>[0];
+  type Tag = Param[number];
+  type Result = ReturnType<typeof listTagsByLetters>;
+
+  test('Should create letters list', () => {
+    const tag1: Tag = {
+      name: 'tag1',
+      permalink: '/tag1',
+      count: 1,
+    };
+    const tag2: Tag = {
+      name: 'Tag2',
+      permalink: '/tag2',
+      count: 11,
+    };
+    const tagzxy: Tag = {
+      name: 'zxy',
+      permalink: '/zxy',
+      count: 987,
+    };
+    const tagAbc: Tag = {
+      name: 'Abc',
+      permalink: '/abc',
+      count: 123,
+    };
+    const tagdef: Tag = {
+      name: 'def',
+      permalink: '/def',
+      count: 1,
+    };
+    const tagaaa: Tag = {
+      name: 'aaa',
+      permalink: '/aaa',
+      count: 10,
+    };
+
+    const expectedResult: Result = [
+      {letter: 'A', tags: [tagaaa, tagAbc]},
+      {letter: 'D', tags: [tagdef]},
+      {letter: 'T', tags: [tag1, tag2]},
+      {letter: 'Z', tags: [tagzxy]},
+    ];
+
+    // Input order shouldn't matter, output is always consistently sorted
+    expect(
+      listTagsByLetters([tag1, tag2, tagzxy, tagAbc, tagdef, tagaaa]),
+    ).toEqual(expectedResult);
+    expect(
+      listTagsByLetters([tagzxy, tagdef, tagaaa, tag2, tagAbc, tag1]),
+    ).toEqual(expectedResult);
+    expect(
+      listTagsByLetters(shuffle([tagzxy, tagdef, tagaaa, tag2, tagAbc, tag1])),
+    ).toEqual(expectedResult);
+  });
+});