@docusaurus/theme-common 2.0.0-beta.18 → 2.0.0-beta.19

package/src/utils/scrollUtils.tsx

@@ -16,6 +16,7 @@ import React, {
 } from 'react';
 import {useDynamicCallback, ReactContextError} from './reactUtils';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 
 type ScrollController = {
   /** A boolean ref tracking whether scroll events are enabled. */
@@ -232,3 +233,76 @@ export function useScrollPositionBlocker(): {
     blockElementScrollPositionUntilNextRender,
   };
 }
+
+type CancelScrollTop = () => void;
+
+function smoothScrollNative(top: number): CancelScrollTop {
+  window.scrollTo({top, behavior: 'smooth'});
+  return () => {
+    // Nothing to cancel, it's natively cancelled if user tries to scroll down
+  };
+}
+
+function smoothScrollPolyfill(top: number): CancelScrollTop {
+  let raf: number | null = null;
+  const isUpScroll = document.documentElement.scrollTop > top;
+  function rafRecursion() {
+    const currentScroll = document.documentElement.scrollTop;
+    if (
+      (isUpScroll && currentScroll > top) ||
+      (!isUpScroll && currentScroll < top)
+    ) {
+      raf = requestAnimationFrame(rafRecursion);
+      window.scrollTo(0, Math.floor((currentScroll - top) * 0.85) + top);
+    }
+  }
+  rafRecursion();
+
+  // Break the recursion. Prevents the user from "fighting" against that
+  // recursion producing a weird UX
+  return () => raf && cancelAnimationFrame(raf);
+}
+
+/**
+ * A "smart polyfill" of `window.scrollTo({ top, behavior: "smooth" })`.
+ * This currently always uses a polyfilled implementation unless
+ * `scroll-behavior: smooth` has been set in CSS, because native support
+ * detection for scroll behavior seems unreliable.
+ *
+ * This hook does not do anything by itself: it returns a start and a stop
+ * handle. You can execute either handle at any time.
+ */
+export function useSmoothScrollTo(): {
+  /**
+   * Start the scroll.
+   *
+   * @param top The final scroll top position.
+   */
+  startScroll: (top: number) => void;
+  /**
+   * A cancel function, because the non-native smooth scroll-top
+   * implementation must be interrupted if user scrolls down. If there's no
+   * existing animation or the scroll is using native behavior, this is a no-op.
+   */
+  cancelScroll: CancelScrollTop;
+} {
+  const cancelRef = useRef<CancelScrollTop | null>(null);
+  const isBrowser = useIsBrowser();
+  // Not all have support for smooth scrolling (particularly Safari mobile iOS)
+  // TODO proper detection is currently unreliable!
+  // see https://github.com/wessberg/scroll-behavior-polyfill/issues/16
+  // For now, we only use native scroll behavior if smooth is already set,
+  // because otherwise the polyfill produces a weird UX when both CSS and JS try
+  // to scroll a page, and they cancel each other.
+  const supportsNativeSmoothScrolling =
+    isBrowser &&
+    getComputedStyle(document.documentElement).scrollBehavior === 'smooth';
+  return {
+    startScroll: (top: number) => {
+      cancelRef.current = supportsNativeSmoothScrolling
+        ? smoothScrollNative(top)
+        : smoothScrollPolyfill(top);
+    },
+    cancelScroll: () => cancelRef.current?.(),
+  };
+}

package/src/utils/searchUtils.ts

@@ -35,6 +35,8 @@ export function useContextualSearchFilters(): {locale: string; tags: string[]} {
   const activePluginAndVersion = useActivePluginAndVersion();
   const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();
 
+  // This can't use more specialized hooks because we are mapping over all
+  // plugin instances.
   function getDocPluginTags(pluginId: string) {
     const activeVersion =
       activePluginAndVersion?.activePlugin?.pluginId === pluginId

package/src/utils/storageUtils.ts

@@ -54,11 +54,11 @@ Possible reasons: running Docusaurus in an iframe, in an incognito browser sessi
 }
 
 // Convenient storage interface for a single storage key
-export interface StorageSlot {
+export type StorageSlot = {
   get: () => string | null;
   set: (value: string) => void;
   del: () => void;
-}
+};
 
 const NoopStorageSlot: StorageSlot = {
   get: () => null,

package/src/utils/tagsUtils.ts

@@ -6,6 +6,7 @@
  */
 
 import {translate} from '@docusaurus/Translate';
+import type {TagsListItem} from '@docusaurus/utils';
 
 export const translateTagsPageTitle = (): string =>
   translate({
@@ -14,13 +15,7 @@ export const translateTagsPageTitle = (): string =>
     description: 'The title of the tag list page',
   });
 
-export type TagsListItem = Readonly<{
-  name: string;
-  permalink: string;
-  count: number;
-}>;
-
-export type TagLetterEntry = Readonly<{letter: string; tags: TagsListItem[]}>;
+export type TagLetterEntry = {letter: string; tags: TagsListItem[]};
 
 function getTagLetter(tag: string): string {
   return tag[0]!.toUpperCase();
@@ -35,7 +30,7 @@ export function listTagsByLetters(
 ): TagLetterEntry[] {
   const groups: {[initial: string]: TagsListItem[]} = {};
   Object.values(tags).forEach((tag) => {
-    const initial = getTagLetter(tag.name);
+    const initial = getTagLetter(tag.label);
     groups[initial] ??= [];
     groups[initial]!.push(tag);
   });
@@ -47,7 +42,7 @@ export function listTagsByLetters(
       .map(([letter, letterTags]) => {
         // Sort tags inside a letter
         const sortedTags = letterTags.sort((tag1, tag2) =>
-          tag1.name.localeCompare(tag2.name),
+          tag1.label.localeCompare(tag2.label),
         );
         return {letter, tags: sortedTags};
       })

package/src/utils/tocUtils.ts

@@ -6,7 +6,7 @@
  */
 
 import {useMemo} from 'react';
-import type {TOCItem} from '@docusaurus/types';
+import type {TOCItem} from '@docusaurus/mdx-loader';
 
 export type TOCTreeNode = {
   readonly value: string;
@@ -30,11 +30,11 @@ function treeifyTOC(flatTOC: readonly TOCItem[]): TOCTreeNode[] {
   const prevIndexForLevel = Array(7).fill(-1);
 
   headings.forEach((curr, currIndex) => {
-    // take the last seen index for each ancestor level. the highest
-    // index will be the direct ancestor of the current heading.
+    // Take the last seen index for each ancestor level. the highest index will
+    // be the direct ancestor of the current heading.
     const ancestorLevelIndexes = prevIndexForLevel.slice(2, curr.level);
     curr.parentIndex = Math.max(...ancestorLevelIndexes);
-    // mark that curr.level was last seen at the current index
+    // Mark that curr.level was last seen at the current index.
     prevIndexForLevel[curr.level] = currIndex;
   });
 
@@ -101,7 +101,7 @@ function filterTOC({
  * to ensure that weird TOC structures preserve their semantics. For example, an
  * h3-h2-h4 sequence should not be treeified as an "h3 > h4" hierarchy with
  * min=3, max=4, but should rather be "[h3, h4]" (since the h2 heading has split
- * the two headings and they are not parents)
+ * the two headings and they are not parent-children)
  */
 export function useFilteredAndTreeifiedTOC({
   toc,

package/src/utils/useThemeConfig.ts

@@ -8,6 +8,7 @@
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import type {PrismTheme} from 'prism-react-renderer';
 import type {DeepPartial} from 'utility-types';
+import type {MagicCommentConfig} from './codeBlockUtils';
 
 export type DocsVersionPersistence = 'localStorage' | 'none';
 
@@ -53,10 +54,11 @@ export type AnnouncementBarConfig = {
 };
 
 export type PrismConfig = {
-  theme?: PrismTheme;
+  theme: PrismTheme;
   darkTheme?: PrismTheme;
   defaultLanguage?: string;
   additionalLanguages: string[];
+  magicComments: MagicCommentConfig[];
 };
 
 export type FooterLinkItem = {
@@ -104,6 +106,10 @@ export type TableOfContents = {
 export type ThemeConfig = {
   docs: {
     versionPersistence: DocsVersionPersistence;
+    sidebar: {
+      hideable: boolean;
+      autoCollapseCategories: boolean;
+    };
   };
 
   // TODO we should complete this theme config type over time
@@ -116,11 +122,8 @@ export type ThemeConfig = {
   announcementBar?: AnnouncementBarConfig;
   prism: PrismConfig;
   footer?: Footer;
-  hideableSidebar: boolean;
-  autoCollapseSidebarCategories: boolean;
   image?: string;
   metadata: Array<{[key: string]: string}>;
-  sidebarCollapsible: boolean;
   tableOfContents: TableOfContents;
 };