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

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';
 
@@ -37,11 +56,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 +77,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 +87,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,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`,
     );

package/src/utils/__tests__/docsUtils.test.tsx

@@ -0,0 +1,331 @@
+/**
+ * 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 from 'react';
+import {renderHook} from '@testing-library/react-hooks';
+import {
+  findFirstCategoryLink,
+  isActiveSidebarItem,
+  DocsVersionProvider,
+  useDocsVersion,
+  useDocById,
+  useDocsSidebar,
+  DocsSidebarProvider,
+  findSidebarCategory,
+} from '../docsUtils';
+import {
+  PropSidebar,
+  PropSidebarItem,
+  PropSidebarItemCategory,
+  PropVersionMetadata,
+} from '@docusaurus/plugin-content-docs';
+
+// Make tests more readable with some useful category item defaults
+function testCategory(
+  data?: Partial<PropSidebarItemCategory>,
+): PropSidebarItemCategory {
+  return {
+    type: 'category',
+    href: undefined,
+    label: 'Category label',
+    items: [],
+    collapsed: true,
+    collapsible: true,
+    ...data,
+  };
+}
+
+function testVersion(data?: Partial<PropVersionMetadata>): PropVersionMetadata {
+  return {
+    version: 'versionName',
+    label: 'Version Label',
+    className: 'version className',
+    badge: true,
+    banner: 'unreleased',
+    docs: {},
+    docsSidebars: {},
+    isLast: false,
+    pluginId: 'default',
+    ...data,
+  };
+}
+
+describe('docsUtils', () => {
+  describe('useDocsVersion', () => {
+    test('should throw if context provider is missing', () => {
+      expect(
+        () => renderHook(() => useDocsVersion()).result.current,
+      ).toThrowErrorMatchingInlineSnapshot(
+        `"This hook requires usage of <DocsVersionProvider>"`,
+      );
+    });
+
+    test('should read value from context provider', () => {
+      const version = testVersion();
+      const {result} = renderHook(() => useDocsVersion(), {
+        wrapper: ({children}) => (
+          <DocsVersionProvider version={version}>
+            {children}
+          </DocsVersionProvider>
+        ),
+      });
+      expect(result.current).toBe(version);
+    });
+  });
+
+  describe('useDocsSidebar', () => {
+    test('should throw if context provider is missing', () => {
+      expect(
+        () => renderHook(() => useDocsSidebar()).result.current,
+      ).toThrowErrorMatchingInlineSnapshot(
+        `"This hook requires usage of <DocsSidebarProvider>"`,
+      );
+    });
+
+    test('should read value from context provider', () => {
+      const sidebar: PropSidebar = [];
+      const {result} = renderHook(() => useDocsSidebar(), {
+        wrapper: ({children}) => (
+          <DocsSidebarProvider sidebar={sidebar}>
+            {children}
+          </DocsSidebarProvider>
+        ),
+      });
+      expect(result.current).toBe(sidebar);
+    });
+  });
+
+  describe('useDocById', () => {
+    const version = testVersion({
+      docs: {
+        doc1: {
+          id: 'doc1',
+          title: 'Doc 1',
+          description: 'desc1',
+          sidebar: 'sidebar1',
+        },
+        doc2: {
+          id: 'doc2',
+          title: 'Doc 2',
+          description: 'desc2',
+          sidebar: 'sidebar2',
+        },
+      },
+    });
+
+    function callHook(docId: string | undefined) {
+      const {result} = renderHook(() => useDocById(docId), {
+        wrapper: ({children}) => (
+          <DocsVersionProvider version={version}>
+            {children}
+          </DocsVersionProvider>
+        ),
+      });
+      return result.current;
+    }
+
+    test('should accept undefined', () => {
+      expect(callHook(undefined)).toBeUndefined();
+    });
+
+    test('should find doc1', () => {
+      expect(callHook('doc1')).toMatchObject({id: 'doc1'});
+    });
+    test('should find doc2', () => {
+      expect(callHook('doc2')).toMatchObject({id: 'doc2'});
+    });
+
+    test('should throw for doc3', () => {
+      expect(() => callHook('doc3')).toThrowErrorMatchingInlineSnapshot(
+        `"no version doc found by id=doc3"`,
+      );
+    });
+  });
+
+  describe('findSidebarCategory', () => {
+    test('should be able to return undefined', () => {
+      expect(findSidebarCategory([], () => false)).toBeUndefined();
+      expect(
+        findSidebarCategory([testCategory(), testCategory()], () => false),
+      ).toBeUndefined();
+    });
+
+    test('should return first element matching predicate', () => {
+      const first = testCategory();
+      const second = testCategory();
+      const third = testCategory();
+      const sidebar = [first, second, third];
+      expect(findSidebarCategory(sidebar, () => true)).toEqual(first);
+      expect(findSidebarCategory(sidebar, (item) => item === first)).toEqual(
+        first,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === second)).toEqual(
+        second,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === third)).toEqual(
+        third,
+      );
+    });
+
+    test('should be able to search in sub items', () => {
+      const subsub1 = testCategory();
+      const subsub2 = testCategory();
+      const sub1 = testCategory({
+        items: [subsub1, subsub2],
+      });
+      const sub2 = testCategory();
+      const parent = testCategory({
+        items: [sub1, sub2],
+      });
+      const sidebar = [parent];
+
+      expect(findSidebarCategory(sidebar, () => true)).toEqual(parent);
+      expect(findSidebarCategory(sidebar, (item) => item === sub1)).toEqual(
+        sub1,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === sub2)).toEqual(
+        sub2,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === subsub1)).toEqual(
+        subsub1,
+      );
+      expect(findSidebarCategory(sidebar, (item) => item === subsub2)).toEqual(
+        subsub2,
+      );
+    });
+  });
+
+  describe('findFirstCategoryLink', () => {
+    test('category without link nor child', () => {
+      expect(
+        findFirstCategoryLink(
+          testCategory({
+            href: undefined,
+          }),
+        ),
+      ).toEqual(undefined);
+    });
+
+    test('category with link', () => {
+      expect(
+        findFirstCategoryLink(
+          testCategory({
+            href: '/itemPath',
+          }),
+        ),
+      ).toEqual('/itemPath');
+    });
+
+    test('category with deeply nested category link', () => {
+      expect(
+        findFirstCategoryLink(
+          testCategory({
+            href: undefined,
+            items: [
+              testCategory({
+                href: undefined,
+                items: [
+                  testCategory({
+                    href: '/itemPath',
+                  }),
+                ],
+              }),
+            ],
+          }),
+        ),
+      ).toEqual('/itemPath');
+    });
+
+    test('category with deeply nested link', () => {
+      expect(
+        findFirstCategoryLink(
+          testCategory({
+            href: undefined,
+            items: [
+              testCategory({
+                href: undefined,
+                items: [{type: 'link', href: '/itemPath', label: 'Label'}],
+              }),
+            ],
+          }),
+        ),
+      ).toEqual('/itemPath');
+    });
+  });
+
+  describe('isActiveSidebarItem', () => {
+    test('with link href', () => {
+      const item: PropSidebarItem = {
+        type: 'link',
+        href: '/itemPath',
+        label: 'Label',
+      };
+
+      expect(isActiveSidebarItem(item, '/unexistingPath')).toEqual(false);
+
+      expect(isActiveSidebarItem(item, '/itemPath')).toEqual(true);
+
+      // Ensure it's not trailing slash sensitive:
+      expect(isActiveSidebarItem(item, '/itemPath/')).toEqual(true);
+      expect(
+        isActiveSidebarItem({...item, href: '/itemPath/'}, '/itemPath'),
+      ).toEqual(true);
+    });
+
+    test('with category href', () => {
+      const item: PropSidebarItem = testCategory({
+        href: '/itemPath',
+      });
+
+      expect(isActiveSidebarItem(item, '/unexistingPath')).toEqual(false);
+
+      expect(isActiveSidebarItem(item, '/itemPath')).toEqual(true);
+
+      // Ensure it's not trailing slash sensitive:
+      expect(isActiveSidebarItem(item, '/itemPath/')).toEqual(true);
+      expect(
+        isActiveSidebarItem({...item, href: '/itemPath/'}, '/itemPath'),
+      ).toEqual(true);
+    });
+
+    test('with category nested items', () => {
+      const item: PropSidebarItem = testCategory({
+        href: '/category-path',
+        items: [
+          {
+            type: 'link',
+            href: '/sub-link-path',
+            label: 'Label',
+          },
+          testCategory({
+            href: '/sub-category-path',
+            items: [
+              {
+                type: 'link',
+                href: '/sub-sub-link-path',
+                label: 'Label',
+              },
+            ],
+          }),
+        ],
+      });
+
+      expect(isActiveSidebarItem(item, '/unexistingPath')).toEqual(false);
+
+      expect(isActiveSidebarItem(item, '/category-path')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-link-path')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-category-path')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-sub-link-path')).toEqual(true);
+
+      // Ensure it's not trailing slash sensitive:
+      expect(isActiveSidebarItem(item, '/category-path/')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-link-path/')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-category-path/')).toEqual(true);
+      expect(isActiveSidebarItem(item, '/sub-sub-link-path/')).toEqual(true);
+    });
+  });
+});

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

@@ -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 {uniq} from '../jsUtils';
+
+describe('uniq', () => {
+  test('remove duplicate primitives', () => {
+    expect(uniq(['A', 'B', 'C', 'B', 'A', 'D'])).toEqual(['A', 'B', 'C', 'D']);
+    expect(uniq([3, 3, 5, 1, 6, 3, 5])).toEqual([3, 5, 1, 6]);
+    expect(uniq([null, undefined, 3, null, 4, 3])).toEqual([
+      null,
+      undefined,
+      3,
+      4,
+    ]);
+  });
+
+  test('remove duplicate objects/arrays by identity', () => {
+    const obj1 = {};
+    const obj2 = {};
+    const obj3 = {};
+    const array1: unknown[] = [];
+    const array2: unknown[] = [];
+    const array3: unknown[] = [];
+    expect(
+      uniq([obj1, obj1, obj2, array1, obj2, array3, array2, array1, obj3]),
+    ).toEqual([obj1, obj2, array1, array3, array2, obj3]);
+  });
+});

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);
+  });
+});