@docusaurus/theme-classic 2.0.0-beta.15d451942 → 2.0.0-beta.16

package/lib-next/theme/Toggle/styles.module.css

@@ -6,23 +6,6 @@
  */
 
 .toggle {
-  align-items: center;
-  display: flex;
-  height: 10px;
-  justify-content: center;
-  width: 10px;
-}
-.toggle::before {
-  position: absolute;
-}
-
-/**
- * styles for React Toggle
- * copied over because we want to allow user to swizzle it and modify the css
- * and also to make sure its compatible with our dark mode
- * https://github.com/aaronshaf/react-toggle/blob/master/style.css
- */
-:global(.react-toggle) {
   touch-action: pan-x;
   position: relative;
   cursor: pointer;
@@ -30,7 +13,7 @@
   -webkit-tap-highlight-color: transparent;
 }
 
-:global(.react-toggle-screenreader-only) {
+.toggleScreenReader {
   border: 0;
   clip: rect(0 0 0 0);
   height: 1px;
@@ -40,11 +23,11 @@
   width: 1px;
 }
 
-:global(.react-toggle--disabled) {
+.toggleDisabled {
   cursor: not-allowed;
 }
 
-:global(.react-toggle-track) {
+.toggleTrack {
   width: 50px;
   height: 24px;
   border-radius: 30px;
@@ -52,42 +35,42 @@
   transition: all 0.2s ease;
 }
 
-:global(.react-toggle-track-check) {
+.toggleTrackCheck {
   position: absolute;
   width: 14px;
   height: 10px;
-  top: 0px;
-  bottom: 0px;
+  top: 0;
+  bottom: 0;
   margin: auto 0;
   left: 8px;
   opacity: 0;
   transition: opacity 0.25s ease;
 }
 
-:global([data-theme='dark'] .react-toggle .react-toggle-track-check),
-:global(.react-toggle--checked .react-toggle-track-check) {
+.toggleChecked .toggleTrackCheck,
+[data-theme='dark'] .toggle .toggleTrackCheck {
   opacity: 1;
   transition: opacity 0.25s ease;
 }
 
-:global(.react-toggle-track-x) {
+.toggleTrackX {
   position: absolute;
   width: 10px;
   height: 10px;
-  top: 0px;
-  bottom: 0px;
+  top: 0;
+  bottom: 0;
   margin: auto 0;
   right: 10px;
   opacity: 1;
   transition: opacity 0.25s ease;
 }
 
-:global([data-theme='dark'] .react-toggle .react-toggle-track-x),
-:global(.react-toggle--checked .react-toggle-track-x) {
+.toggleChecked .toggleTrackX,
+[data-theme='dark'] .toggle .toggleTrackX {
   opacity: 0;
 }
 
-:global(.react-toggle-thumb) {
+.toggleTrackThumb {
   position: absolute;
   top: 1px;
   left: 1px;
@@ -99,16 +82,25 @@
   transition: all 0.25s ease;
 }
 
-:global([data-theme='dark'] .react-toggle .react-toggle-thumb),
-:global(.react-toggle--checked .react-toggle-thumb) {
+.toggleFocused .toggleTrackThumb,
+.toggle:hover .toggleTrackThumb {
+  box-shadow: 0 0 2px 3px var(--ifm-color-primary);
+}
+
+/* stylelint-disable-next-line no-descending-specificity */
+.toggleChecked .toggleTrackThumb,
+[data-theme='dark'] .toggle .toggleTrackThumb {
   left: 27px;
 }
 
-:global(.react-toggle--focus .react-toggle-thumb),
-:global(.react-toggle:hover .react-toggle-thumb) {
-  box-shadow: 0px 0px 2px 3px var(--ifm-color-primary);
+.toggle:active:not(.toggleDisabled) .toggleTrackThumb {
+  box-shadow: 0 0 5px 5px var(--ifm-color-primary);
 }
 
-:global(.react-toggle:active:not(.react-toggle--disabled) .react-toggle-thumb) {
-  box-shadow: 0px 0px 5px 5px var(--ifm-color-primary);
+.toggleIcon {
+  align-items: center;
+  display: flex;
+  height: 10px;
+  justify-content: center;
+  width: 10px;
 }

package/lib-next/theme/prism-include-languages.js

@@ -4,20 +4,22 @@
  * 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 siteConfig from '@generated/docusaurus.config';
+export default function prismIncludeLanguages(PrismObject) {
+  const {
+    themeConfig: {prism},
+  } = siteConfig;
+  const {additionalLanguages} = prism; // Prism components work on the Prism instance on the window, while prism-
+  // react-renderer uses its own Prism instance. We temporarily mount the
+  // instance onto window, import components to enhance it, then remove it to
+  // avoid polluting global namespace.
+  // You can mutate PrismObject: registering plugins, deleting languages... As
+  // long as you don't re-assign it
 
-const prismIncludeLanguages = (PrismObject) => {
-  if (ExecutionEnvironment.canUseDOM) {
-    const {
-      themeConfig: {prism: {additionalLanguages = []} = {}},
-    } = siteConfig;
-    window.Prism = PrismObject;
-    additionalLanguages.forEach((lang) => {
-      require(`prismjs/components/prism-${lang}`); // eslint-disable-line
-    });
-    delete window.Prism;
-  }
-};
-
-export default prismIncludeLanguages;
+  globalThis.Prism = PrismObject;
+  additionalLanguages.forEach((lang) => {
+    // eslint-disable-next-line global-require, import/no-dynamic-require
+    require(`prismjs/components/prism-${lang}`);
+  });
+  delete globalThis.Prism;
+}

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "2.0.0-beta.15d451942",
+  "version": "2.0.0-beta.16",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
-  "types": "src/types.d.ts",
+  "types": "src/theme-classic.d.ts",
   "publishConfig": {
     "access": "public"
   },
@@ -14,49 +14,50 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsc --noEmit && yarn babel:lib && yarn babel:lib-next && yarn prettier:lib-next",
-    "watch": "concurrently -n \"lib,lib-next\" --kill-others \"yarn babel:lib --watch\" \"yarn babel:lib-next --watch\"",
+    "build": "tsc --noEmit && yarn babel:lib && yarn babel:lib-next && yarn format:lib-next",
+    "watch": "concurrently --names \"lib,lib-next,tsc\" --kill-others \"yarn babel:lib --watch\" \"yarn babel:lib-next --watch\" \"yarn tsc --watch\"",
     "babel:lib": "cross-env BABEL_ENV=lib babel src -d lib --extensions \".tsx,.ts\" --ignore \"**/*.d.ts\" --copy-files",
     "babel:lib-next": "cross-env BABEL_ENV=lib-next babel src -d lib-next --extensions \".tsx,.ts\" --ignore \"**/*.d.ts\" --copy-files",
-    "prettier": "prettier --config ../../.prettierrc --ignore-path ../../.prettierignore --write \"**/*.{js,ts,jsx,tsc}\"",
-    "prettier:lib-next": "prettier --config ../../.prettierrc --write \"lib-next/**/*.{js,ts,jsx,tsc}\"",
-    "update-code-translations": "node -e 'require(\"./update-code-translations.js\").run()'"
+    "format:lib-next": "prettier --config ../../.prettierrc --write \"lib-next/**/*.{js,ts,jsx,tsc}\""
   },
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.15d451942",
-    "@docusaurus/plugin-content-blog": "2.0.0-beta.15d451942",
-    "@docusaurus/plugin-content-docs": "2.0.0-beta.15d451942",
-    "@docusaurus/plugin-content-pages": "2.0.0-beta.15d451942",
-    "@docusaurus/theme-common": "2.0.0-beta.15d451942",
-    "@docusaurus/types": "2.0.0-beta.15d451942",
-    "@docusaurus/utils": "2.0.0-beta.15d451942",
-    "@docusaurus/utils-validation": "2.0.0-beta.15d451942",
-    "@mdx-js/mdx": "^1.6.21",
-    "@mdx-js/react": "^1.6.21",
-    "chalk": "^4.1.1",
+    "@docusaurus/core": "2.0.0-beta.16",
+    "@docusaurus/plugin-content-blog": "2.0.0-beta.16",
+    "@docusaurus/plugin-content-docs": "2.0.0-beta.16",
+    "@docusaurus/plugin-content-pages": "2.0.0-beta.16",
+    "@docusaurus/theme-common": "2.0.0-beta.16",
+    "@docusaurus/theme-translations": "2.0.0-beta.16",
+    "@docusaurus/utils": "2.0.0-beta.16",
+    "@docusaurus/utils-common": "2.0.0-beta.16",
+    "@docusaurus/utils-validation": "2.0.0-beta.16",
+    "@mdx-js/react": "^1.6.22",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.0.1",
-    "fs-extra": "^10.0.0",
-    "globby": "^11.0.2",
-    "infima": "0.2.0-alpha.24",
-    "lodash": "^4.17.20",
-    "parse-numeric-range": "^1.2.0",
-    "postcss": "^8.2.15",
+    "infima": "0.2.0-alpha.37",
+    "lodash": "^4.17.21",
+    "postcss": "^8.4.6",
     "prism-react-renderer": "^1.2.1",
-    "prismjs": "^1.23.0",
-    "prop-types": "^15.7.2",
+    "prismjs": "^1.27.0",
     "react-router-dom": "^5.2.0",
-    "rtlcss": "^3.1.2"
+    "rtlcss": "^3.3.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.15d451942"
+    "@docusaurus/module-type-aliases": "2.0.0-beta.16",
+    "@docusaurus/types": "2.0.0-beta.16",
+    "@types/mdx-js__react": "^1.5.5",
+    "@types/prismjs": "^1.26.0",
+    "@types/rtlcss": "^3.1.2",
+    "cross-env": "^7.0.3",
+    "fs-extra": "^10.0.1",
+    "react-test-renderer": "^17.0.2",
+    "utility-types": "^3.10.0"
   },
   "peerDependencies": {
     "react": "^16.8.4 || ^17.0.0",
     "react-dom": "^16.8.4 || ^17.0.0"
   },
   "engines": {
-    "node": ">=12.13.0"
+    "node": ">=14"
   },
-  "gitHead": "dfceae8bd3e8b42ba8fc14f1449d861046c26143"
+  "gitHead": "eb43c4d4f95a4fb97dc9bb9dc615413e0dc2e1e7"
 }

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

@@ -0,0 +1,101 @@
+/**
+ * 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 type {SwizzleConfig} from '@docusaurus/types';
+
+export default function getSwizzleConfig(): SwizzleConfig {
+  return {
+    components: {
+      CodeBlock: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description:
+          'The component used to render multi-line code blocks, generally used in Markdown files.',
+      },
+      DocSidebar: {
+        actions: {
+          wrap: 'safe',
+          eject: 'unsafe', // too much technical code in sidebar, not very safe atm
+        },
+        description: 'The sidebar component on docs pages',
+      },
+      Footer: {
+        actions: {
+          wrap: 'safe',
+          eject: 'unsafe', // TODO split footer into smaller parts
+        },
+        description: "The footer component of you site's layout",
+      },
+      NotFound: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description:
+          'The global 404 page of your site, meant to be ejected and customized',
+      },
+      SearchBar: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        // TODO how to describe this one properly?
+        // By default it's an empty placeholder for the user to fill
+        description:
+          'The search bar component of your site, appearing in the navbar.',
+      },
+      IconArrow: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description: 'The arrow icon component',
+      },
+      IconEdit: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description: 'The edit icon component',
+      },
+      IconMenu: {
+        actions: {
+          wrap: 'safe',
+          eject: 'safe',
+        },
+        description: 'The menu icon component',
+      },
+
+      'prism-include-languages': {
+        actions: {
+          wrap: 'forbidden', // not a component!
+          eject: 'safe',
+        },
+        description:
+          'The Prism languages to include for code block syntax highlighting. Meant to be ejected.',
+      },
+      MDXComponents: {
+        actions: {
+          wrap: 'forbidden', /// TODO allow wrapping objects???
+          eject: 'safe',
+        },
+        description:
+          'The MDX components to use for rendering MDX files. Meant to be ejected.',
+      },
+
+      // TODO should probably not even appear here
+      'NavbarItem/utils': {
+        actions: {
+          wrap: 'forbidden',
+          eject: 'forbidden',
+        },
+      },
+    },
+  };
+}

package/src/index.ts

@@ -5,28 +5,30 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {DocusaurusContext, Plugin} from '@docusaurus/types';
-import {ThemeConfig} from '@docusaurus/theme-common';
+import type {LoadContext, Plugin, PostCssOptions} from '@docusaurus/types';
+import type {ThemeConfig} from '@docusaurus/theme-common';
 import {getTranslationFiles, translateThemeConfig} from './translations';
 import path from 'path';
-import Module from 'module';
-import type {AcceptedPlugin, Result, Plugin as PostCssPlugin} from 'postcss';
+import {createRequire} from 'module';
+import type {Plugin as PostCssPlugin} from 'postcss';
 import rtlcss from 'rtlcss';
-import {readDefaultCodeTranslationMessages} from '@docusaurus/utils';
+import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
+import type {Options} from '@docusaurus/theme-classic';
+import type webpack from 'webpack';
 
-const createRequire = Module.createRequire || Module.createRequireFromPath;
 const requireFromDocusaurusCore = createRequire(
   require.resolve('@docusaurus/core/package.json'),
 );
-const ContextReplacementPlugin = requireFromDocusaurusCore(
-  'webpack/lib/ContextReplacementPlugin',
-);
+const ContextReplacementPlugin: typeof webpack.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 noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
-  return `(function() {
+// Make sure the key is the same as the one in `/theme/hooks/useTheme.js`
+const ThemeStorageKey = 'theme';
+const noFlashColorMode = ({
+  defaultMode,
+  respectPrefersColorScheme,
+}: ThemeConfig['colorMode']) => `(function() {
   var defaultMode = '${defaultMode}';
   var respectPrefersColorScheme = ${respectPrefersColorScheme};
 
@@ -37,7 +39,7 @@ const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
   function getStoredTheme() {
     var theme = null;
     try {
-      theme = localStorage.getItem('${storageKey}');
+      theme = localStorage.getItem('${ThemeStorageKey}');
     } catch (err) {}
     return theme;
   }
@@ -61,59 +63,75 @@ const noFlashColorMode = ({defaultMode, respectPrefersColorScheme}) => {
     }
   }
 })();`;
-};
 
-function getInfimaCSSFile(direction) {
+// 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
+export const AnnouncementBarDismissStorageKey =
+  'docusaurus.announcement.dismiss';
+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: string) {
   return `infima/dist/css/default/default${
     direction === 'rtl' ? '-rtl' : ''
   }.css`;
 }
 
-type PluginOptions = {
-  customCss?: string;
-};
-
 export default function docusaurusThemeClassic(
-  context: DocusaurusContext, // TODO: LoadContext is missing some of properties
-  options: PluginOptions,
+  context: LoadContext,
+  options: Options,
 ): Plugin<void> {
   const {
     siteConfig: {themeConfig: roughlyTypedThemeConfig},
     i18n: {currentLocale, localeConfigs},
   } = context;
   const themeConfig = (roughlyTypedThemeConfig || {}) as ThemeConfig;
-  const {colorMode, prism: {additionalLanguages = []} = {}} = themeConfig;
+  const {
+    announcementBar,
+    colorMode,
+    prism: {additionalLanguages = []} = {},
+  } = themeConfig;
   const {customCss} = options || {};
   const {direction} = localeConfigs[currentLocale];
 
   return {
     name: 'docusaurus-theme-classic',
 
-    /*
-    Does not seem needed: webpack can already hot reload theme files
-    getPathsToWatch() {
-      return [
-        path.join(__dirname, '..', 'lib'),
-        path.join(__dirname, '..', 'lib-next'),
-      ];
-    },
-     */
-
     getThemePath() {
-      return path.join(__dirname, '..', 'lib-next', 'theme');
+      return path.join(__dirname, '../lib-next/theme');
     },
 
     getTypeScriptThemePath() {
-      return path.resolve(__dirname, '..', 'src', 'theme');
+      return path.resolve(__dirname, '../src/theme');
     },
 
     getTranslationFiles: async () => getTranslationFiles({themeConfig}),
-    translateThemeConfig,
 
-    getDefaultCodeTranslationMessages: () => {
+    translateThemeConfig: (params) =>
+      translateThemeConfig({
+        themeConfig: params.themeConfig as ThemeConfig,
+        translationFiles: params.translationFiles,
+      }),
+
+    getDefaultCodeTranslationMessages() {
       return readDefaultCodeTranslationMessages({
-        dirPath: path.resolve(__dirname, '..', 'codeTranslations'),
         locale: currentLocale,
+        name: 'theme-common',
       });
     },
 
@@ -121,6 +139,7 @@ export default function docusaurusThemeClassic(
       const modules = [
         require.resolve(getInfimaCSSFile(direction)),
         path.resolve(__dirname, './prism-include-languages'),
+        path.resolve(__dirname, './admonitions.css'),
       ];
 
       if (customCss) {
@@ -140,11 +159,10 @@ export default function docusaurusThemeClassic(
         .join('|');
 
       return {
-        ignoreWarnings: [
-          // See https://github.com/facebook/docusaurus/pull/3382
-          (e) => e.message.includes("Can't resolve '@theme-init/hooks/useDocs"),
-        ],
         plugins: [
+          // This allows better optimization by only bundling those components
+          // that the user actually needs, because the modules are dynamically
+          // required and can't be known during compile time.
           new ContextReplacementPlugin(
             /prismjs[\\/]components$/,
             new RegExp(`^./(${prismLanguages})$`),
@@ -153,18 +171,18 @@ export default function docusaurusThemeClassic(
       };
     },
 
-    configurePostCss(postCssOptions: {plugins: AcceptedPlugin[]}) {
+    configurePostCss(postCssOptions: PostCssOptions) {
       if (direction === 'rtl') {
         const resolvedInfimaFile = require.resolve(getInfimaCSSFile(direction));
         const plugin: PostCssPlugin = {
           postcssPlugin: 'RtlCssPlugin',
-          prepare: (result: Result) => {
+          prepare: (result) => {
             const file = result.root?.source?.input?.file;
             // Skip Infima as we are using the its RTL version.
             if (file === resolvedInfimaFile) {
               return {};
             }
-            return rtlcss(result.root);
+            return rtlcss(result.root as unknown as rtlcss.ConfigOptions);
           },
         };
         postCssOptions.plugins.push(plugin);
@@ -178,10 +196,10 @@ export default function docusaurusThemeClassic(
         preBodyTags: [
           {
             tagName: 'script',
-            attributes: {
-              type: 'text/javascript',
-            },
-            innerHTML: noFlashColorMode(colorMode),
+            innerHTML: `
+${noFlashColorMode(colorMode)}
+${announcementBar ? AnnouncementBarInlineJavaScript : ''}
+            `,
           },
         ],
       };
@@ -189,21 +207,5 @@ export default function docusaurusThemeClassic(
   };
 }
 
-const swizzleAllowedComponents = [
-  'CodeBlock',
-  'DocSidebar',
-  'Footer',
-  'NotFound',
-  'SearchBar',
-  'IconArrow',
-  'IconEdit',
-  'IconMenu',
-  'hooks/useTheme',
-  'prism-include-languages',
-];
-
-export function getSwizzleComponentList(): string[] {
-  return swizzleAllowedComponents;
-}
-
+export {default as getSwizzleConfig} from './getSwizzleConfig';
 export {validateThemeConfig} from './validateThemeConfig';