@docusaurus/theme-common 2.0.0-beta.12faed89d → 2.0.0-beta.14

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,43 @@ export {useThemeConfig} from './utils/useThemeConfig';
 
 export type {
   ThemeConfig,
+  UserThemeConfig,
   Navbar,
   NavbarItem,
   NavbarLogo,
+  MultiColumnFooter,
+  SimpleFooter,
   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';
 
@@ -37,11 +57,14 @@ export {useLocationChange} from './utils/useLocationChange';
 
 export {usePrevious} from './utils/usePrevious';
 
-export {useCollapsible, Collapsible} from './utils/useCollapsible';
+export {useCollapsible, Collapsible} from './components/Collapsible';
 export type {
   UseCollapsibleConfig,
   UseCollapsibleReturns,
-} from './utils/useCollapsible';
+} from './components/Collapsible';
+
+export {default as Details} from './components/Details';
+export type {DetailsProps} from './components/Details';
 
 export {
   MobileSecondaryMenuProvider,
@@ -55,6 +78,8 @@ export {
   useDocsPreferredVersionByPluginId,
 } from './utils/docsPreferredVersion/useDocsPreferredVersion';
 
+export {duplicates, uniq} from './utils/jsUtils';
+
 export {DocsPreferredVersionContextProvider} from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
 
 export {ThemeClassNames} from './utils/ThemeClassNames';
@@ -63,3 +88,29 @@ 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,58 @@
  */
 
 // 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',
+    codeBlock: 'theme-code-block',
+  },
+  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/announcementBarUtils.tsx

@@ -14,7 +14,7 @@ import React, {
   useContext,
   createContext,
 } from 'react';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import {createStorageSlot} from './storageUtils';
 import {useThemeConfig} from './useThemeConfig';
 
@@ -33,21 +33,21 @@ const setDismissedInStorage = (bool: boolean) =>
   AnnouncementBarDismissStorage.set(String(bool));
 
 type AnnouncementBarAPI = {
-  readonly isClosed: boolean;
+  readonly isActive: boolean;
   readonly close: () => void;
 };
 
 const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
   const {announcementBar} = useThemeConfig();
-  const {isClient} = useDocusaurusContext();
+  const isBrowser = useIsBrowser();
 
-  const [isClosed, setClosed] = useState(() => {
-    return isClient
+  const [isClosed, setClosed] = useState(() =>
+    isBrowser
       ? // On client navigation: init with localstorage value
         isDismissedInStorage()
       : // On server/hydration: always visible to prevent layout shifts (will be hidden with css if needed)
-        false;
-  });
+        false,
+  );
   // Update state after hydration
   useEffect(() => {
     setClosed(isDismissedInStorage());
@@ -83,26 +83,31 @@ const useAnnouncementBarContextValue = (): AnnouncementBarAPI => {
     if (isNewAnnouncement || !isDismissedInStorage()) {
       setClosed(false);
     }
-  }, []);
+  }, [announcementBar]);
 
-  return useMemo(() => {
-    return {
-      isClosed,
+  return useMemo(
+    () => ({
+      isActive: !!announcementBar && !isClosed,
       close: handleClose,
-    };
-  }, [isClosed]);
+    }),
+    [announcementBar, isClosed, handleClose],
+  );
 };
 
 const AnnouncementBarContext = createContext<AnnouncementBarAPI | null>(null);
 
-export const AnnouncementBarProvider = ({children}: {children: ReactNode}) => {
+export function AnnouncementBarProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
   const value = useAnnouncementBarContextValue();
   return (
     <AnnouncementBarContext.Provider value={value}>
       {children}
     </AnnouncementBarContext.Provider>
   );
-};
+}
 
 export const useAnnouncementBar = (): AnnouncementBarAPI => {
   const api = useContext(AnnouncementBarContext);

package/src/utils/codeBlockUtils.ts

@@ -5,8 +5,159 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import rangeParser from 'parse-numeric-range';
+import type {Language} from 'prism-react-renderer';
+
 const codeBlockTitleRegex = /title=(["'])(.*?)\1/;
+const highlightLinesRangeRegex = /{([\d,-]+)}/;
+
+const commentTypes = ['js', 'jsBlock', 'jsx', 'python', 'html'] as const;
+type CommentType = typeof commentTypes[number];
+
+type CommentPattern = {
+  start: string;
+  end: string;
+};
+
+// Supported types of highlight comments
+const commentPatterns: Record<CommentType, CommentPattern> = {
+  js: {
+    start: '\\/\\/',
+    end: '',
+  },
+  jsBlock: {
+    start: '\\/\\*',
+    end: '\\*\\/',
+  },
+  jsx: {
+    start: '\\{\\s*\\/\\*',
+    end: '\\*\\/\\s*\\}',
+  },
+  python: {
+    start: '#',
+    end: '',
+  },
+  html: {
+    start: '<!--',
+    end: '-->',
+  },
+};
+
+const magicCommentDirectives = [
+  'highlight-next-line',
+  'highlight-start',
+  'highlight-end',
+];
+
+const getMagicCommentDirectiveRegex = (
+  languages: readonly CommentType[] = commentTypes,
+) => {
+  // to be more reliable, the opening and closing comment must match
+  const commentPattern = languages
+    .map((lang) => {
+      const {start, end} = commentPatterns[lang];
+      return `(?:${start}\\s*(${magicCommentDirectives.join('|')})\\s*${end})`;
+    })
+    .join('|');
+  // white space is allowed, but otherwise it should be on it's own line
+  return new RegExp(`^\\s*(?:${commentPattern})\\s*$`);
+};
+
+// select comment styles based on language
+const magicCommentDirectiveRegex = (lang: string) => {
+  switch (lang) {
+    case 'js':
+    case 'javascript':
+    case 'ts':
+    case 'typescript':
+      return getMagicCommentDirectiveRegex(['js', 'jsBlock']);
+
+    case 'jsx':
+    case 'tsx':
+      return getMagicCommentDirectiveRegex(['js', 'jsBlock', 'jsx']);
+
+    case 'html':
+      return getMagicCommentDirectiveRegex(['js', 'jsBlock', 'html']);
+
+    case 'python':
+    case 'py':
+      return getMagicCommentDirectiveRegex(['python']);
+
+    default:
+      // all comment types
+      return getMagicCommentDirectiveRegex();
+  }
+};
 
 export function parseCodeBlockTitle(metastring?: string): string {
   return metastring?.match(codeBlockTitleRegex)?.[2] ?? '';
 }
+
+export function parseLanguage(className?: string): Language | undefined {
+  const languageClassName = className
+    ?.split(' ')
+    .find((str) => str.startsWith('language-'));
+  return languageClassName?.replace(/language-/, '') as Language | undefined;
+}
+
+/**
+ * @param metastring The highlight range declared here starts at 1
+ * @returns Note: all line numbers start at 0, not 1
+ */
+export function parseLines(
+  content: string,
+  metastring?: string,
+  language?: Language,
+): {
+  highlightLines: number[];
+  code: string;
+} {
+  let code = content.replace(/\n$/, '');
+  // Highlighted lines specified in props: don't parse the content
+  if (metastring && highlightLinesRangeRegex.test(metastring)) {
+    const highlightLinesRange = metastring.match(highlightLinesRangeRegex)![1];
+    const highlightLines = rangeParser(highlightLinesRange)
+      .filter((n) => n > 0)
+      .map((n) => n - 1);
+    return {highlightLines, code};
+  }
+  if (language === undefined) {
+    return {highlightLines: [], code};
+  }
+  const directiveRegex = magicCommentDirectiveRegex(language);
+  // go through line by line
+  const lines = code.split('\n');
+  let highlightBlockStart: number;
+  let highlightRange = '';
+  // loop through lines
+  for (let lineNumber = 0; lineNumber < lines.length; ) {
+    const line = lines[lineNumber];
+    const match = line.match(directiveRegex);
+    if (match !== null) {
+      const directive = match.slice(1).find((item) => item !== undefined);
+      switch (directive) {
+        case 'highlight-next-line':
+          highlightRange += `${lineNumber},`;
+          break;
+
+        case 'highlight-start':
+          highlightBlockStart = lineNumber;
+          break;
+
+        case 'highlight-end':
+          highlightRange += `${highlightBlockStart!}-${lineNumber - 1},`;
+          break;
+
+        default:
+          break;
+      }
+      lines.splice(lineNumber, 1);
+    } else {
+      // lines without directives are unchanged
+      lineNumber += 1;
+    }
+  }
+  const highlightLines = rangeParser(highlightRange);
+  code = lines.join('\n');
+  return {highlightLines, code};
+}

package/src/utils/docsPreferredVersion/DocsPreferredVersionProvider.tsx

@@ -4,6 +4,7 @@
  * 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,
   ReactNode,
@@ -15,7 +16,7 @@ import React, {
 import {useThemeConfig, DocsVersionPersistence} from '../useThemeConfig';
 import {isDocsPluginEnabled} from '../docsUtils';
 
-import {useAllDocsData} from '@theme/hooks/useDocs';
+import {useAllDocsData, GlobalPluginData} from '@theme/hooks/useDocs';
 
 import DocsPreferredVersionStorage from './DocsPreferredVersionStorage';
 
@@ -54,7 +55,7 @@ function readStorageState({
 }: {
   pluginIds: string[];
   versionPersistence: DocsVersionPersistence;
-  allDocsData: any; // TODO find a way to type it :(
+  allDocsData: Record<string, GlobalPluginData>;
 }): DocsPreferredVersionState {
   // The storage value we read might be stale,
   // and belong to a version that does not exist in the site anymore
@@ -68,7 +69,7 @@ function readStorageState({
     );
     const pluginData = allDocsData[pluginId];
     const versionExists = pluginData.versions.some(
-      (version: any) => version.name === preferredVersionNameUnsafe,
+      (version) => version.name === preferredVersionNameUnsafe,
     );
     if (versionExists) {
       return {preferredVersionName: preferredVersionNameUnsafe};
@@ -120,7 +121,7 @@ function useContextValue() {
     return {
       savePreferredVersion,
     };
-  }, [setState]);
+  }, [versionPersistence]);
 
   return [state, api] as const;
 }
@@ -132,7 +133,7 @@ const Context = createContext<DocsPreferredVersionContextValue | null>(null);
 export function DocsPreferredVersionContextProvider({
   children,
 }: {
-  children: ReactNode;
+  children: JSX.Element;
 }): JSX.Element {
   if (isDocsPluginEnabled) {
     return (
@@ -141,7 +142,7 @@ export function DocsPreferredVersionContextProvider({
       </DocsPreferredVersionContextProviderUnsafe>
     );
   } else {
-    return <>{children}</>;
+    return children;
   }
 }
 

package/src/utils/docsPreferredVersion/DocsPreferredVersionStorage.ts

@@ -22,9 +22,8 @@ const DocsPreferredVersionStorage = {
   read: (
     pluginId: string,
     persistence: DocsVersionPersistence,
-  ): string | null => {
-    return createStorageSlot(storageKey(pluginId), {persistence}).get();
-  },
+  ): string | null =>
+    createStorageSlot(storageKey(pluginId), {persistence}).get(),
 
   clear: (pluginId: string, persistence: DocsVersionPersistence): void => {
     createStorageSlot(storageKey(pluginId), {persistence}).del();