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

package/src/components/Collapsible/index.tsx

@@ -0,0 +1,242 @@
+/**
+ * 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 ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+import React, {
+  useState,
+  useEffect,
+  useRef,
+  useCallback,
+  RefObject,
+  Dispatch,
+  SetStateAction,
+  ReactNode,
+  useLayoutEffect,
+} from 'react';
+
+const DefaultAnimationEasing = 'ease-in-out';
+
+export type UseCollapsibleConfig = {
+  initialState: boolean | (() => boolean);
+};
+
+export type UseCollapsibleReturns = {
+  collapsed: boolean;
+  setCollapsed: Dispatch<SetStateAction<boolean>>;
+  toggleCollapsed: () => void;
+};
+
+// This hook just define the state
+export function useCollapsible({
+  initialState,
+}: UseCollapsibleConfig): UseCollapsibleReturns {
+  const [collapsed, setCollapsed] = useState(initialState ?? false);
+
+  const toggleCollapsed = useCallback(() => {
+    setCollapsed((expanded) => !expanded);
+  }, []);
+
+  return {
+    collapsed,
+    setCollapsed,
+    toggleCollapsed,
+  };
+}
+
+const CollapsedStyles = {
+  display: 'none',
+  overflow: 'hidden',
+  height: '0px',
+} as const;
+
+const ExpandedStyles = {
+  display: 'block',
+  overflow: 'visible',
+  height: 'auto',
+} as const;
+
+function applyCollapsedStyle(el: HTMLElement, collapsed: boolean) {
+  const collapsedStyles = collapsed ? CollapsedStyles : ExpandedStyles;
+  el.style.display = collapsedStyles.display;
+  el.style.overflow = collapsedStyles.overflow;
+  el.style.height = collapsedStyles.height;
+}
+
+/*
+Lex111: Dynamic transition duration is used in Material design, this technique is good for a large number of items.
+https://material.io/archive/guidelines/motion/duration-easing.html#duration-easing-dynamic-durations
+https://github.com/mui-org/material-ui/blob/e724d98eba018e55e1a684236a2037e24bcf050c/packages/material-ui/src/styles/createTransitions.js#L40-L43
+ */
+function getAutoHeightDuration(height: number) {
+  const constant = height / 36;
+  return Math.round((4 + 15 * constant ** 0.25 + constant / 5) * 10);
+}
+
+type CollapsibleAnimationConfig = {
+  duration?: number;
+  easing?: string;
+};
+
+function useCollapseAnimation({
+  collapsibleRef,
+  collapsed,
+  animation,
+}: {
+  collapsibleRef: RefObject<HTMLElement>;
+  collapsed: boolean;
+  animation?: CollapsibleAnimationConfig;
+}) {
+  const mounted = useRef(false);
+
+  useEffect(() => {
+    const el = collapsibleRef.current!;
+
+    function getTransitionStyles() {
+      const height = el.scrollHeight;
+      const duration = animation?.duration ?? getAutoHeightDuration(height);
+      const easing = animation?.easing ?? DefaultAnimationEasing;
+      return {
+        transition: `height ${duration}ms ${easing}`,
+        height: `${height}px`,
+      };
+    }
+
+    function applyTransitionStyles() {
+      const transitionStyles = getTransitionStyles();
+      el.style.transition = transitionStyles.transition;
+      el.style.height = transitionStyles.height;
+    }
+
+    // On mount, we just apply styles, no animated transition
+    if (!mounted.current) {
+      applyCollapsedStyle(el, collapsed);
+      mounted.current = true;
+      return undefined;
+    }
+
+    el.style.willChange = 'height';
+
+    function startAnimation() {
+      const animationFrame = requestAnimationFrame(() => {
+        // When collapsing
+        if (collapsed) {
+          applyTransitionStyles();
+
+          requestAnimationFrame(() => {
+            el.style.height = CollapsedStyles.height;
+            el.style.overflow = CollapsedStyles.overflow;
+          });
+        }
+        // When expanding
+        else {
+          el.style.display = 'block';
+          requestAnimationFrame(() => {
+            applyTransitionStyles();
+          });
+        }
+      });
+
+      return () => cancelAnimationFrame(animationFrame);
+    }
+
+    return startAnimation();
+  }, [collapsibleRef, collapsed, animation]);
+}
+
+type CollapsibleElementType = React.ElementType<
+  Pick<React.HTMLAttributes<unknown>, 'className' | 'onTransitionEnd' | 'style'>
+>;
+
+// Prevent hydration layout shift before anims are handled imperatively with JS
+function getSSRStyle(collapsed: boolean) {
+  if (ExecutionEnvironment.canUseDOM) {
+    return undefined;
+  }
+  return collapsed ? CollapsedStyles : ExpandedStyles;
+}
+
+type CollapsibleBaseProps = {
+  as?: CollapsibleElementType;
+  collapsed: boolean;
+  children: ReactNode;
+  animation?: CollapsibleAnimationConfig;
+  onCollapseTransitionEnd?: (collapsed: boolean) => void;
+  className?: string;
+
+  // This is mostly useful for details/summary component where ssrStyle is not needed (as details are hidden natively)
+  // and can mess-up with the default native behavior of the browser when JS fails to load or is disabled
+  disableSSRStyle?: boolean;
+};
+
+function CollapsibleBase({
+  as: As = 'div',
+  collapsed,
+  children,
+  animation,
+  onCollapseTransitionEnd,
+  className,
+  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: the "too complicated type" is produced from "CollapsibleElementType" being a huge union
+      ref={collapsibleRef}
+      style={disableSSRStyle ? undefined : getSSRStyle(collapsed)}
+      onTransitionEnd={(e: React.TransitionEvent) => {
+        if (e.propertyName !== 'height') {
+          return;
+        }
+
+        applyCollapsedStyle(collapsibleRef.current!, collapsed);
+        onCollapseTransitionEnd?.(collapsed);
+      }}
+      className={className}>
+      {children}
+    </As>
+  );
+}
+
+function CollapsibleLazy({collapsed, ...props}: CollapsibleBaseProps) {
+  const [mounted, setMounted] = useState(!collapsed);
+
+  useLayoutEffect(() => {
+    if (!collapsed) {
+      setMounted(true);
+    }
+  }, [collapsed]);
+
+  // lazyCollapsed updated in effect so that the first expansion transition can work
+  const [lazyCollapsed, setLazyCollapsed] = useState(collapsed);
+  useLayoutEffect(() => {
+    if (mounted) {
+      setLazyCollapsed(collapsed);
+    }
+  }, [mounted, collapsed]);
+
+  return mounted ? (
+    <CollapsibleBase {...props} collapsed={lazyCollapsed} />
+  ) : null;
+}
+
+type CollapsibleProps = CollapsibleBaseProps & {
+  // Lazy allows to delay the rendering when collapsed => it will render children only after hydration, on first expansion
+  // Required prop: it forces to think if content should be server-rendered or not!
+  // This has perf impact on the SSR output and html file sizes
+  // See https://github.com/facebook/docusaurus/issues/4753
+  lazy: boolean;
+};
+
+export function Collapsible({lazy, ...props}: CollapsibleProps): JSX.Element {
+  const Comp = lazy ? CollapsibleLazy : CollapsibleBase;
+  return <Comp {...props} />;
+}

package/src/components/Details/index.tsx

@@ -0,0 +1,94 @@
+/**
+ * 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, {ComponentProps, ReactElement, 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: HTMLElement | null): boolean {
+  if (!node) {
+    return false;
+  }
+  return node.tagName === 'SUMMARY' || isInSummary(node.parentElement);
+}
+
+function hasParent(node: HTMLElement | null, parent: HTMLElement): boolean {
+  if (!node) {
+    return false;
+  }
+  return node === parent || hasParent(node.parentElement, parent);
+}
+
+export type DetailsProps = {
+  summary?: ReactElement;
+} & ComponentProps<'details'>;
+
+function Details({summary, children, ...props}: DetailsProps): JSX.Element {
+  const isBrowser = useIsBrowser();
+  const detailsRef = useRef<HTMLDetailsElement>(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 (
+    <details
+      {...props}
+      ref={detailsRef}
+      open={open}
+      data-collapsed={collapsed}
+      className={clsx(
+        styles.details,
+        {[styles.isBrowser]: isBrowser},
+        props.className,
+      )}
+      onMouseDown={(e) => {
+        const target = e.target as HTMLElement;
+        // 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 as HTMLElement;
+        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}
+
+      <Collapsible
+        lazy={false} // Content might matter for SEO in this case
+        collapsed={collapsed}
+        disableSSRStyle // Allows component to work fine even with JS disabled!
+        onCollapseTransitionEnd={(newCollapsed) => {
+          setCollapsed(newCollapsed);
+          setOpen(!newCollapsed);
+        }}>
+        <div className={styles.collapsibleContent}>{children}</div>
+      </Collapsible>
+    </details>
+  );
+}
+
+export default Details;

package/src/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/src/index.ts

@@ -9,23 +9,42 @@ export {useThemeConfig} 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';
 
@@ -33,13 +52,64 @@ 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/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__/codeBlockUtils.test.ts

@@ -28,13 +28,13 @@ describe('parseCodeBlockTitle', () => {
     expect(parseCodeBlockTitle(`{1,2-3}`)).toEqual(``);
   });
 
-  test('should parse with multiple metadatas title first', () => {
+  test('should parse with multiple metadata title first', () => {
     expect(parseCodeBlockTitle(`title="index.js" label="JavaScript"`)).toEqual(
       `index.js`,
     );
   });
 
-  test('should parse with multiple metadatas title last', () => {
+  test('should parse with multiple metadata title last', () => {
     expect(parseCodeBlockTitle(`label="JavaScript" title="index.js"`)).toEqual(
       `index.js`,
     );