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

package/README.md

@@ -28,4 +28,4 @@ module.exports = {
 $ npm swizzle @docusaurus/theme-classic [component name]
 ```
 
-All components used by this theme can be found [here](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/src/theme)
+All components used by this theme can be found [here](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme)

package/lib/__tests__/validateThemeConfig.test.js

@@ -91,6 +91,10 @@ describe('themeConfig', () => {
         },
         copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc. Built with Docusaurus.`,
       },
+      tableOfContents: {
+        minHeadingLevel: 2,
+        maxHeadingLevel: 5,
+      },
     };
     expect(testValidateThemeConfig(userConfig)).toEqual({
       ...DEFAULT_CONFIG,
@@ -108,7 +112,6 @@ describe('themeConfig', () => {
             position: 'left',
             docId: 'intro',
             label: 'Introduction',
-            activeSidebarClassName: 'custom-class',
           },
           // Regular link
           {
@@ -134,6 +137,23 @@ describe('themeConfig', () => {
               },
             ],
           },
+          // Dropdown with name
+          {
+            type: 'dropdown',
+            label: 'Tools',
+            position: 'left',
+            items: [
+              {
+                type: 'doc',
+                docId: 'npm',
+                label: 'NPM',
+              },
+              {
+                to: '/yarn',
+                label: 'Yarn',
+              },
+            ],
+          },
           // Doc version dropdown
           {
             type: 'docsVersionDropdown',
@@ -141,8 +161,7 @@ describe('themeConfig', () => {
             dropdownActiveClassDisabled: true,
             dropdownItemsBefore: [
               {
-                href:
-                  'https://www.npmjs.com/package/docusaurus?activeTab=versions',
+                href: 'https://www.npmjs.com/package/docusaurus?activeTab=versions',
                 label: 'Versions on npm',
                 className: 'npm-styled',
                 target: '_self',
@@ -181,6 +200,112 @@ describe('themeConfig', () => {
     });
   });
 
+  test('should reject unknown navbar item type', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            type: 'joke',
+            position: 'left',
+            label: 'haha',
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(`"Bad navbar item type joke"`);
+  });
+
+  test('should reject nested dropdowns', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            position: 'left',
+            label: 'Nested',
+            items: [
+              {
+                label: 'Still a dropdown',
+                items: [
+                  {
+                    label: 'Should reject this',
+                    to: '/rejected',
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(`"Nested dropdowns are not allowed"`);
+  });
+
+  test('should reject nested dropdowns', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            position: 'left',
+            label: 'Nested',
+            items: [{type: 'docsVersionDropdown'}],
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(`"Nested dropdowns are not allowed"`);
+  });
+
+  test('should reject position attribute within dropdown', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            position: 'left',
+            label: 'Dropdown',
+            items: [
+              {
+                label: 'Hi',
+                position: 'left',
+                to: '/link',
+              },
+            ],
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"navbar.items[0].items[0].position\\" is not allowed"`,
+    );
+  });
+
+  test('should give friendly error when href and to coexist', () => {
+    const config = {
+      navbar: {
+        items: [
+          {
+            position: 'left',
+            label: 'Nested',
+            to: '/link',
+            href: 'http://example.com/link',
+          },
+        ],
+      },
+    };
+    expect(() =>
+      testValidateThemeConfig(config),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"One and only one between \\"to\\" and \\"href\\" should be provided"`,
+    );
+  });
+
   test('should allow empty alt tags for the logo image in the header', () => {
     const altTagConfig = {
       navbar: {
@@ -220,6 +345,27 @@ describe('themeConfig', () => {
     });
   });
 
+  test('should allow width and height specification for logo ', () => {
+    const altTagConfig = {
+      navbar: {
+        logo: {
+          alt: '',
+          src: '/arbitrary-logo.png',
+          srcDark: '/arbitrary-dark-logo.png',
+          width: '20px',
+          height: '20%',
+        },
+      },
+    };
+    expect(testValidateThemeConfig(altTagConfig)).toEqual({
+      ...DEFAULT_CONFIG,
+      navbar: {
+        ...DEFAULT_CONFIG.navbar,
+        ...altTagConfig.navbar,
+      },
+    });
+  });
+
   test('should accept valid prism config', () => {
     const prismConfig = {
       prism: {
@@ -331,3 +477,131 @@ describe('themeConfig', () => {
     });
   });
 });
+
+describe('themeConfig tableOfContents', () => {
+  test('toc undefined', () => {
+    const tableOfContents = undefined;
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: DEFAULT_CONFIG.tableOfContents.minHeadingLevel,
+        maxHeadingLevel: DEFAULT_CONFIG.tableOfContents.maxHeadingLevel,
+      },
+    });
+  });
+
+  test('toc empty', () => {
+    const tableOfContents = {};
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: DEFAULT_CONFIG.tableOfContents.minHeadingLevel,
+        maxHeadingLevel: DEFAULT_CONFIG.tableOfContents.maxHeadingLevel,
+      },
+    });
+  });
+
+  test('toc with min', () => {
+    const tableOfContents = {
+      minHeadingLevel: 3,
+    };
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: 3,
+        maxHeadingLevel: DEFAULT_CONFIG.tableOfContents.maxHeadingLevel,
+      },
+    });
+  });
+
+  test('toc with max', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 5,
+    };
+    expect(testValidateThemeConfig({tableOfContents})).toEqual({
+      ...DEFAULT_CONFIG,
+      tableOfContents: {
+        minHeadingLevel: DEFAULT_CONFIG.tableOfContents.minHeadingLevel,
+        maxHeadingLevel: 5,
+      },
+    });
+  });
+
+  test('toc with min 2.5', () => {
+    const tableOfContents = {
+      minHeadingLevel: 2.5,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be an integer"`,
+    );
+  });
+
+  test('toc with max 2.5', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 2.5,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.maxHeadingLevel\\" must be an integer"`,
+    );
+  });
+
+  test('toc with min 1', () => {
+    const tableOfContents = {
+      minHeadingLevel: 1,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be greater than or equal to 2"`,
+    );
+  });
+
+  test('toc with min 7', () => {
+    const tableOfContents = {
+      minHeadingLevel: 7,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be less than or equal to ref:maxHeadingLevel"`,
+    );
+  });
+
+  test('toc with max 1', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 1,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.maxHeadingLevel\\" must be greater than or equal to 2"`,
+    );
+  });
+
+  test('toc with max 7', () => {
+    const tableOfContents = {
+      maxHeadingLevel: 7,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.maxHeadingLevel\\" must be less than or equal to 6"`,
+    );
+  });
+
+  test('toc with bad min 5 + max 3', () => {
+    const tableOfContents = {
+      minHeadingLevel: 5,
+      maxHeadingLevel: 3,
+    };
+    expect(() =>
+      testValidateThemeConfig({tableOfContents}),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `"\\"tableOfContents.minHeadingLevel\\" must be less than or equal to ref:maxHeadingLevel"`,
+    );
+  });
+});

package/lib/admonitions.css

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+
+.admonition h5 {
+  margin-top: 0;
+  margin-bottom: 8px;
+  text-transform: uppercase;
+}
+
+.admonition-icon {
+  display: inline-block;
+  vertical-align: middle;
+  margin-right: 0.4em;
+}
+
+.admonition-icon svg {
+  display: inline-block;
+  width: 22px;
+  height: 22px;
+  stroke-width: 0;
+  fill: var(--ifm-alert-foreground-color);
+  stroke: var(--ifm-alert-foreground-color);
+}
+
+.admonition-content > :last-child {
+  margin-bottom: 0;
+}
+
+.admonition {
+  margin-bottom: 1em;
+}

package/lib/deps.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+
+declare module 'prism-react-renderer/prism' {
+  import type * as PrismNamespace from 'prismjs';
+
+  const Prism: typeof PrismNamespace;
+  export default Prism;
+}

package/lib/index.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+exports.AnnouncementBarDismissStorageKey = void 0;
 exports.default = docusaurusThemeClassic;
 exports.getSwizzleComponentList = getSwizzleComponentList;
 Object.defineProperty(exports, "validateThemeConfig", {
@@ -16,11 +17,11 @@ var _translations = require("./translations");
 
 var _path = _interopRequireDefault(require("path"));
 
-var _module = _interopRequireDefault(require("module"));
+var _module = require("module");
 
 var _rtlcss = _interopRequireDefault(require("rtlcss"));
 
-var _utils = require("@docusaurus/utils");
+var _themeTranslations = require("@docusaurus/theme-translations");
 
 var _validateThemeConfig = require("./validateThemeConfig");
 
@@ -32,18 +33,16 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-const createRequire = _module.default.createRequire || _module.default.createRequireFromPath;
-const requireFromDocusaurusCore = createRequire(require.resolve('@docusaurus/core/package.json'));
+const requireFromDocusaurusCore = (0, _module.createRequire)(require.resolve('@docusaurus/core/package.json'));
 const ContextReplacementPlugin = requireFromDocusaurusCore('webpack/lib/ContextReplacementPlugin'); // Need to be inlined to prevent dark mode FOUC
 // Make sure that the 'storageKey' is the same as the one in `/theme/hooks/useTheme.js`
 
-const storageKey = 'theme';
+const ThemeStorageKey = 'theme';
 
 const noFlashColorMode = ({
   defaultMode,
   respectPrefersColorScheme
-}) => {
-  return `(function() {
+}) => `(function() {
   var defaultMode = '${defaultMode}';
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
@@ -54,7 +53,7 @@ const noFlashColorMode = ({
   function getStoredTheme() {
     var theme = null;
     try {
-      theme = localStorage.getItem('${storageKey}');
+      theme = localStorage.getItem('${ThemeStorageKey}');
     } catch (err) {}
     return theme;
   }
@@ -77,8 +76,26 @@ const noFlashColorMode = ({
       setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
     }
   }
+})();`; // Duplicated constant. Unfortunately we can't import it from theme-common, as we need to support older nodejs versions without ESM support
+// TODO: import from theme-common once we only support Node.js with ESM support
+// + move all those announcementBar stuff there too
+
+
+const AnnouncementBarDismissStorageKey = 'docusaurus.announcement.dismiss';
+exports.AnnouncementBarDismissStorageKey = AnnouncementBarDismissStorageKey;
+const AnnouncementBarDismissDataAttribute = 'data-announcement-bar-initially-dismissed'; // We always render the announcement bar html on the server, to prevent layout shifts on React hydration
+// The theme can use CSS + the data attribute to hide the announcement bar asap (before React hydration)
+
+const AnnouncementBarInlineJavaScript = `
+(function() {
+  function isDismissed() {
+    try {
+      return localStorage.getItem('${AnnouncementBarDismissStorageKey}') === 'true';
+    } catch (err) {}
+    return false;
+  }
+  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
 })();`;
-};
 
 function getInfimaCSSFile(direction) {
   return `infima/dist/css/default/default${direction === 'rtl' ? '-rtl' : ''}.css`;
@@ -97,6 +114,7 @@ options) {
   } = context;
   const themeConfig = roughlyTypedThemeConfig || {};
   const {
+    announcementBar,
     colorMode,
     prism: {
       additionalLanguages = []
@@ -131,16 +149,20 @@ options) {
     getTranslationFiles: async () => (0, _translations.getTranslationFiles)({
       themeConfig
     }),
-    translateThemeConfig: _translations.translateThemeConfig,
-    getDefaultCodeTranslationMessages: () => {
-      return (0, _utils.readDefaultCodeTranslationMessages)({
-        dirPath: _path.default.resolve(__dirname, '..', 'codeTranslations'),
-        locale: currentLocale
+    translateThemeConfig: params => (0, _translations.translateThemeConfig)({
+      themeConfig: params.themeConfig,
+      translationFiles: params.translationFiles
+    }),
+
+    getDefaultCodeTranslationMessages() {
+      return (0, _themeTranslations.readDefaultCodeTranslationMessages)({
+        locale: currentLocale,
+        name: 'theme-common'
       });
     },
 
     getClientModules() {
-      const modules = [require.resolve(getInfimaCSSFile(direction)), _path.default.resolve(__dirname, './prism-include-languages')];
+      const modules = [require.resolve(getInfimaCSSFile(direction)), _path.default.resolve(__dirname, './prism-include-languages'), _path.default.resolve(__dirname, './admonitions.css')];
 
       if (customCss) {
         if (Array.isArray(customCss)) {
@@ -190,7 +212,10 @@ options) {
       return {
         preBodyTags: [{
           tagName: 'script',
-          innerHTML: noFlashColorMode(colorMode)
+          innerHTML: `
+${noFlashColorMode(colorMode)}
+${announcementBar ? AnnouncementBarInlineJavaScript : ''}
+            `
         }]
       };
     }

package/lib/prism-include-languages.js

@@ -1,11 +1,15 @@
+"use strict";
+
+var _prism = _interopRequireDefault(require("prism-react-renderer/prism"));
+
+var _prismIncludeLanguages = _interopRequireDefault(require("@theme/prism-include-languages"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
 /**
  * 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 Prism from 'prism-react-renderer/prism';
-import prismIncludeLanguages from '@theme/prism-include-languages';
-
-prismIncludeLanguages(Prism);
+(0, _prismIncludeLanguages.default)(_prism.default);

package/lib/theme/AnnouncementBar/index.js

@@ -11,10 +11,10 @@ var _clsx = _interopRequireDefault(require("clsx"));
 
 var _themeCommon = require("@docusaurus/theme-common");
 
-var _useUserPreferencesContext = _interopRequireDefault(require("@theme/hooks/useUserPreferencesContext"));
-
 var _Translate = require("@docusaurus/Translate");
 
+var _IconClose = _interopRequireDefault(require("@theme/IconClose"));
+
 var _stylesModule = _interopRequireDefault(require("./styles.module.css"));
 
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
@@ -27,14 +27,14 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  */
 function AnnouncementBar() {
   const {
-    isAnnouncementBarClosed,
-    closeAnnouncementBar
-  } = (0, _useUserPreferencesContext.default)();
+    isActive,
+    close
+  } = (0, _themeCommon.useAnnouncementBar)();
   const {
     announcementBar
   } = (0, _themeCommon.useThemeConfig)();
 
-  if (!announcementBar) {
+  if (!isActive) {
     return null;
   }
 
@@ -44,28 +44,22 @@ function AnnouncementBar() {
     textColor,
     isCloseable
   } = announcementBar;
-
-  if (!content || isCloseable && isAnnouncementBarClosed) {
-    return null;
-  }
-
   return <div className={_stylesModule.default.announcementBar} style={{
     backgroundColor,
     color: textColor
   }} role="banner">
-      <div className={(0, _clsx.default)(_stylesModule.default.announcementBarContent, {
-      [_stylesModule.default.announcementBarCloseable]: isCloseable
-    })} // Developer provided the HTML, so assume it's safe.
+      {isCloseable && <div className={_stylesModule.default.announcementBarPlaceholder} />}
+      <div className={_stylesModule.default.announcementBarContent} // Developer provided the HTML, so assume it's safe.
     // eslint-disable-next-line react/no-danger
     dangerouslySetInnerHTML={{
       __html: content
     }} />
-      {isCloseable ? <button type="button" className={(0, _clsx.default)(_stylesModule.default.announcementBarClose, 'clean-btn')} onClick={closeAnnouncementBar} aria-label={(0, _Translate.translate)({
+      {isCloseable ? <button type="button" className={(0, _clsx.default)('clean-btn close', _stylesModule.default.announcementBarClose)} onClick={close} aria-label={(0, _Translate.translate)({
       id: 'theme.AnnouncementBar.closeButtonAriaLabel',
       message: 'Close',
       description: 'The ARIA label for close button of announcement bar'
     })}>
-          <span aria-hidden="true">×</span>
+          <_IconClose.default width={14} height={14} strokeWidth={3.1} />
         </button> : null}
     </div>;
 }

package/lib/theme/AnnouncementBar/styles.module.css

@@ -10,55 +10,39 @@
 }
 
 .announcementBar {
-  position: relative;
-  width: 100%;
+  display: flex;
+  align-items: center;
   height: var(--docusaurus-announcement-bar-height);
   background-color: var(--ifm-color-white);
   color: var(--ifm-color-black);
   border-bottom: 1px solid var(--ifm-color-emphasis-100);
 }
 
-@media print {
-  .announcementBar {
-    display: none;
-  }
+html[data-announcement-bar-initially-dismissed='true'] .announcementBar {
+  display: none;
 }
 
-@media screen and (min-width: 1024px) {
-  :root {
-    --docusaurus-announcement-bar-height: 30px;
-  }
+.announcementBarPlaceholder {
+  flex: 0 0 10px;
 }
 
 .announcementBarClose {
-  position: absolute;
-  right: 0;
-  top: 0;
-  width: 55px;
-  font-size: 1.25rem;
-  height: 100%;
+  flex: 0 0 30px;
+  align-self: stretch;
+  padding: 0;
+  line-height: 0;
 }
 
 .announcementBarContent {
+  flex: 1 1 auto;
   font-size: 85%;
-  width: 100%;
   text-align: center;
   padding: 5px 0;
 }
 
-.announcementBarCloseable {
-  margin-right: 55px;
-}
-
-@media screen and (max-width: 576px) {
-  .announcementBarClose {
-    width: 35px;
-  }
-  .announcementBarContent {
-    width: auto;
-  }
-  .announcementBarCloseable {
-    margin-right: 35px;
+@media print {
+  .announcementBar {
+    display: none;
   }
 }
 
@@ -66,3 +50,14 @@
   color: inherit;
   text-decoration: underline;
 }
+
+@media (min-width: 997px) {
+  :root {
+    --docusaurus-announcement-bar-height: 30px;
+  }
+
+  .announcementBarPlaceholder,
+  .announcementBarClose {
+    flex-basis: 50px;
+  }
+}