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

package/lib/getSwizzleConfig.js

@@ -0,0 +1,102 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = getSwizzleConfig;
+
+/**
+ * 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.
+ */
+function getSwizzleConfig() {
+  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/lib/index.js

@@ -5,7 +5,12 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.AnnouncementBarDismissStorageKey = void 0;
 exports.default = docusaurusThemeClassic;
-exports.getSwizzleComponentList = getSwizzleComponentList;
+Object.defineProperty(exports, "getSwizzleConfig", {
+  enumerable: true,
+  get: function () {
+    return _getSwizzleConfig.default;
+  }
+});
 Object.defineProperty(exports, "validateThemeConfig", {
   enumerable: true,
   get: function () {
@@ -23,6 +28,8 @@ var _rtlcss = _interopRequireDefault(require("rtlcss"));
 
 var _themeTranslations = require("@docusaurus/theme-translations");
 
+var _getSwizzleConfig = _interopRequireDefault(require("./getSwizzleConfig"));
+
 var _validateThemeConfig = require("./validateThemeConfig");
 
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
@@ -35,7 +42,7 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  */
 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`
+// Make sure the key is the same as the one in `/theme/hooks/useTheme.js`
 
 const ThemeStorageKey = 'theme';
 
@@ -76,15 +83,17 @@ 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
+})();`; // 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 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() {
@@ -212,10 +221,4 @@ ${announcementBar ? AnnouncementBarInlineJavaScript : ''}
     }
 
   };
-}
-
-const swizzleAllowedComponents = ['CodeBlock', 'DocSidebar', 'Footer', 'NotFound', 'SearchBar', 'IconArrow', 'IconEdit', 'IconMenu', 'hooks/useTheme', 'prism-include-languages'];
-
-function getSwizzleComponentList() {
-  return swizzleAllowedComponents;
 }

package/lib/theme-classic.d.ts

@@ -24,8 +24,7 @@ declare module '@theme/Admonition' {
 }
 
 declare module '@theme/AnnouncementBar' {
-  const AnnouncementBar: () => JSX.Element | null;
-  export default AnnouncementBar;
+  export default function AnnouncementBar(): JSX.Element | null;
 }
 
 declare module '@theme/BackToTopButton' {
@@ -38,9 +37,21 @@ declare module '@theme/BlogListPaginator' {
   export interface Props {
     readonly metadata: Metadata;
   }
+  export default function BlogListPaginator(props: Props): JSX.Element;
+}
+
+declare module '@theme/BlogSidebar' {
+  export type BlogSidebarItem = {title: string; permalink: string};
+  export type BlogSidebar = {
+    title: string;
+    items: BlogSidebarItem[];
+  };
 
-  const BlogListPaginator: (props: Props) => JSX.Element;
-  export default BlogListPaginator;
+  export interface Props {
+    readonly sidebar: BlogSidebar;
+  }
+
+  export default function BlogSidebar(props: Props): JSX.Element;
 }
 
 declare module '@theme/BlogPostItem' {
@@ -56,8 +67,7 @@ declare module '@theme/BlogPostItem' {
     readonly children: JSX.Element;
   }
 
-  const BlogPostItem: (props: Props) => JSX.Element;
-  export default BlogPostItem;
+  export default function BlogPostItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/BlogPostAuthor' {
@@ -90,8 +100,7 @@ declare module '@theme/BlogPostPaginator' {
     readonly prevItem?: Item;
   }
 
-  const BlogPostPaginator: (props: Props) => JSX.Element;
-  export default BlogPostPaginator;
+  export default function BlogPostPaginator(props: Props): JSX.Element;
 }
 
 declare module '@theme/BlogLayout' {
@@ -104,8 +113,7 @@ declare module '@theme/BlogLayout' {
     readonly toc?: ReactNode;
   }
 
-  const BlogLayout: (props: Props) => JSX.Element;
-  export default BlogLayout;
+  export default function BlogLayout(props: Props): JSX.Element;
 }
 
 declare module '@theme/CodeBlock' {
@@ -119,8 +127,33 @@ declare module '@theme/CodeBlock' {
     readonly language?: string;
   }
 
-  const CodeBlock: (props: Props) => JSX.Element;
-  export default CodeBlock;
+  export default function CodeBlock(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocCard' {
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly item: PropSidebarItem;
+  }
+
+  export default function DocCard(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocCardList' {
+  import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly items: PropSidebarItem[];
+  }
+
+  export default function DocCardList(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocItemFooter' {
+  import type {Props} from '@theme/DocItem';
+
+  export default function DocItemFooter(props: Props): JSX.Element;
 }
 
 declare module '@theme/DocPaginator' {
@@ -144,8 +177,7 @@ declare module '@theme/DocSidebar' {
     readonly [key: string]: unknown;
   }
 
-  const DocSidebar: (props: Props) => JSX.Element;
-  export default DocSidebar;
+  export default function DocSidebar(props: Props): JSX.Element;
 }
 
 declare module '@theme/DocSidebarItem' {
@@ -167,24 +199,38 @@ declare module '@theme/DocSidebarItems' {
   import type {Props as DocSidebarItemProps} from '@theme/DocSidebarItem';
   import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 
-  export type Props = Omit<DocSidebarItemProps, 'item' | 'index'> & {
+  export interface Props extends Omit<DocSidebarItemProps, 'item' | 'index'> {
     readonly items: readonly PropSidebarItem[];
-  };
+  }
 
   export default function DocSidebarItems(props: Props): JSX.Element;
 }
 
+declare module '@theme/DocVersionBanner' {
+  export interface Props {
+    readonly className?: string;
+  }
+
+  export default function DocVersionBanner(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocVersionBadge' {
+  export interface Props {
+    readonly className?: string;
+  }
+
+  export default function DocVersionBadge(props: Props): JSX.Element;
+}
+
 declare module '@theme/DocVersionSuggestions' {
-  const DocVersionSuggestions: () => JSX.Element;
-  export default DocVersionSuggestions;
+  export default function DocVersionSuggestions(): JSX.Element;
 }
 
 declare module '@theme/EditThisPage' {
   export interface Props {
     readonly editUrl: string;
   }
-  const EditThisPage: (props: Props) => JSX.Element;
-  export default EditThisPage;
+  export default function EditThisPage(props: Props): JSX.Element;
 }
 
 declare module '@theme/ErrorPageContent' {
@@ -195,8 +241,7 @@ declare module '@theme/ErrorPageContent' {
 }
 
 declare module '@theme/Footer' {
-  const Footer: () => JSX.Element | null;
-  export default Footer;
+  export default function Footer(): JSX.Element | null;
 }
 
 declare module '@theme/Heading' {
@@ -258,8 +303,7 @@ declare module '@theme/SearchMetadata' {
     readonly tag?: string;
   }
 
-  const SearchMetadata: (props: Props) => JSX.Element;
-  export default SearchMetadata;
+  export default function SearchMetadata(props: Props): JSX.Element;
 }
 
 declare module '@theme/LastUpdated' {
@@ -269,13 +313,11 @@ declare module '@theme/LastUpdated' {
     readonly lastUpdatedBy?: string;
   }
 
-  const LastUpdated: (props: Props) => JSX.Element;
-  export default LastUpdated;
+  export default function LastUpdated(props: Props): JSX.Element;
 }
 
 declare module '@theme/SkipToContent' {
-  const SkipToContent: () => JSX.Element;
-  export default SkipToContent;
+  export default function SkipToContent(): JSX.Element;
 }
 
 declare module '@theme/MDXComponents' {
@@ -302,8 +344,7 @@ declare module '@theme/MDXComponents' {
 }
 
 declare module '@theme/Navbar' {
-  const Navbar: () => JSX.Element;
-  export default Navbar;
+  export default function Navbar(): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/DefaultNavbarItem' {
@@ -324,15 +365,15 @@ declare module '@theme/NavbarItem/DefaultNavbarItem' {
 
 declare module '@theme/NavbarItem/NavbarNavLink' {
   import type {ReactNode} from 'react';
-  import type {LinkProps} from '@docusaurus/Link';
+  import type {Props as LinkProps} from '@docusaurus/Link';
 
-  export type Props = LinkProps & {
+  export interface Props extends LinkProps {
     readonly activeBasePath?: string;
     readonly activeBaseRegex?: string;
     readonly exact?: boolean;
     readonly label?: ReactNode;
     readonly prependBaseUrlToHref?: string;
-  };
+  }
 
   export default function NavbarNavLink(props: Props): JSX.Element;
 }
@@ -352,8 +393,7 @@ declare module '@theme/NavbarItem/DropdownNavbarItem' {
     readonly mobile?: boolean;
   }
 
-  const DropdownNavbarItem: (props: Props) => JSX.Element;
-  export default DropdownNavbarItem;
+  export default function DropdownNavbarItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/SearchNavbarItem' {
@@ -361,8 +401,7 @@ declare module '@theme/NavbarItem/SearchNavbarItem' {
     readonly mobile?: boolean;
   }
 
-  const SearchNavbarItem: (props: Props) => JSX.Element;
-  export default SearchNavbarItem;
+  export default function SearchNavbarItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/LocaleDropdownNavbarItem' {
@@ -374,8 +413,7 @@ declare module '@theme/NavbarItem/LocaleDropdownNavbarItem' {
     readonly dropdownItemsAfter: LinkLikeNavbarItemProps[];
   }
 
-  const LocaleDropdownNavbarItem: (props: Props) => JSX.Element;
-  export default LocaleDropdownNavbarItem;
+  export default function LocaleDropdownNavbarItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/DocsVersionDropdownNavbarItem' {
@@ -389,8 +427,9 @@ declare module '@theme/NavbarItem/DocsVersionDropdownNavbarItem' {
     readonly dropdownItemsAfter: LinkLikeNavbarItemProps[];
   }
 
-  const DocsVersionDropdownNavbarItem: (props: Props) => JSX.Element;
-  export default DocsVersionDropdownNavbarItem;
+  export default function DocsVersionDropdownNavbarItem(
+    props: Props,
+  ): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/DocsVersionNavbarItem' {
@@ -400,8 +439,7 @@ declare module '@theme/NavbarItem/DocsVersionNavbarItem' {
     readonly docsPluginId?: string;
   }
 
-  const DocsVersionNavbarItem: (props: Props) => JSX.Element;
-  export default DocsVersionNavbarItem;
+  export default function DocsVersionNavbarItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/DocNavbarItem' {
@@ -412,8 +450,7 @@ declare module '@theme/NavbarItem/DocNavbarItem' {
     readonly docsPluginId?: string;
   }
 
-  const DocsSidebarNavbarItem: (props: Props) => JSX.Element;
-  export default DocsSidebarNavbarItem;
+  export default function DocsSidebarNavbarItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/DocSidebarNavbarItem' {
@@ -424,8 +461,7 @@ declare module '@theme/NavbarItem/DocSidebarNavbarItem' {
     readonly docsPluginId?: string;
   }
 
-  const DocSidebarNavbarItem: (props: Props) => JSX.Element;
-  export default DocSidebarNavbarItem;
+  export default function DocSidebarNavbarItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/NavbarItem' {
@@ -461,8 +497,7 @@ declare module '@theme/NavbarItem' {
 
   export type Types = Props['type'];
 
-  const NavbarItem: (props: Props) => JSX.Element;
-  export default NavbarItem;
+  export default function NavbarItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/utils' {
@@ -498,8 +533,7 @@ declare module '@theme/TabItem' {
     readonly attributes?: Record<string, unknown>;
   }
 
-  const TabItem: (props: Props) => JSX.Element;
-  export default TabItem;
+  export default function TabItem(props: Props): JSX.Element;
 }
 
 declare module '@theme/Tabs' {
@@ -520,8 +554,7 @@ declare module '@theme/Tabs' {
     readonly className?: string;
   }
 
-  const Tabs: (props: Props) => JSX.Element;
-  export default Tabs;
+  export default function Tabs(props: Props): JSX.Element;
 }
 
 declare module '@theme/ThemedImage' {
@@ -534,8 +567,7 @@ declare module '@theme/ThemedImage' {
     };
   }
 
-  const ThemedImage: (props: Props) => JSX.Element;
-  export default ThemedImage;
+  export default function ThemedImage(props: Props): JSX.Element;
 }
 
 declare module '@theme/Details' {
@@ -548,68 +580,56 @@ declare module '@theme/Details' {
 declare module '@theme/TOCItems' {
   import type {TOCItem} from '@docusaurus/types';
 
-  export type TOCItemsProps = {
+  export interface Props {
     readonly toc: readonly TOCItem[];
     readonly minHeadingLevel?: number;
     readonly maxHeadingLevel?: number;
     readonly className?: string;
     readonly linkClassName?: string | null;
     readonly linkActiveClassName?: string;
-  };
+  }
 
-  export default function TOCItems(props: TOCItemsProps): JSX.Element;
+  export default function TOCItems(props: Props): JSX.Element;
 }
 
 declare module '@theme/TOC' {
   import type {TOCItem} from '@docusaurus/types';
 
-  // minHeadingLevel only exists as a per-doc option,
-  // and won't have a default set by Joi. See TOC, TOCInline,
-  // TOCCollapsible for examples
-  export type TOCProps = {
+  // minHeadingLevel only exists as a per-doc option, and won't have a default
+  // set by Joi. See TOC, TOCInline, TOCCollapsible for examples
+  export interface Props {
     readonly toc: readonly TOCItem[];
     readonly minHeadingLevel?: number;
     readonly maxHeadingLevel?: number;
     readonly className?: string;
-  };
-
-  export type TOCHeadingsProps = {
-    readonly toc: readonly TOCItem[];
-    readonly minHeadingLevel?: number;
-    readonly maxHeadingLevel?: number;
-  };
-
-  export const TOCHeadings: (props: TOCHeadingsProps) => JSX.Element;
+  }
 
-  const TOC: (props: TOCProps) => JSX.Element;
-  export default TOC;
+  export default function TOC(props: Props): JSX.Element;
 }
 
 declare module '@theme/TOCInline' {
   import type {TOCItem} from '@docusaurus/types';
 
-  export type TOCInlineProps = {
+  export interface Props {
     readonly toc: readonly TOCItem[];
     readonly minHeadingLevel?: number;
     readonly maxHeadingLevel?: number;
-  };
+  }
 
-  const TOCInline: (props: TOCInlineProps) => JSX.Element;
-  export default TOCInline;
+  export default function TOCInline(props: Props): JSX.Element;
 }
 
 declare module '@theme/TOCCollapsible' {
   import type {TOCItem} from '@docusaurus/types';
 
-  export type TOCCollapsibleProps = {
+  export interface Props {
     readonly className?: string;
     readonly minHeadingLevel?: number;
     readonly maxHeadingLevel?: number;
     readonly toc: readonly TOCItem[];
-  };
+  }
 
-  const TOCCollapsible: (props: TOCCollapsibleProps) => JSX.Element;
-  export default TOCCollapsible;
+  export default function TOCCollapsible(props: Props): JSX.Element;
 }
 
 declare module '@theme/Toggle' {
@@ -621,8 +641,7 @@ declare module '@theme/Toggle' {
     readonly onChange: (e: SyntheticEvent) => void;
   }
 
-  const Toggle: (props: Props) => JSX.Element;
-  export default Toggle;
+  export default function Toggle(props: Props): JSX.Element;
 }
 
 declare module '@theme/Logo' {
@@ -633,8 +652,7 @@ declare module '@theme/Logo' {
     readonly titleClassName?: string;
   }
 
-  const Logo: (props: Props) => JSX.Element;
-  export default Logo;
+  export default function Logo(props: Props): JSX.Element;
 }
 
 declare module '@theme/IconArrow' {
@@ -642,8 +660,7 @@ declare module '@theme/IconArrow' {
 
   export interface Props extends ComponentProps<'svg'> {}
 
-  const IconArrow: (props: Props) => JSX.Element;
-  export default IconArrow;
+  export default function IconArrow(props: Props): JSX.Element;
 }
 
 declare module '@theme/IconEdit' {
@@ -651,8 +668,7 @@ declare module '@theme/IconEdit' {
 
   export interface Props extends ComponentProps<'svg'> {}
 
-  const IconEdit: (props: Props) => JSX.Element;
-  export default IconEdit;
+  export default function IconEdit(props: Props): JSX.Element;
 }
 
 declare module '@theme/IconMenu' {
@@ -660,8 +676,7 @@ declare module '@theme/IconMenu' {
 
   export interface Props extends ComponentProps<'svg'> {}
 
-  const IconMenu: (props: Props) => JSX.Element;
-  export default IconMenu;
+  export default function IconMenu(props: Props): JSX.Element;
 }
 
 declare module '@theme/IconClose' {
@@ -669,8 +684,7 @@ declare module '@theme/IconClose' {
 
   export interface Props extends ComponentProps<'svg'> {}
 
-  const IconClose: (props: Props) => JSX.Element;
-  export default IconClose;
+  export default function IconClose(props: Props): JSX.Element;
 }
 
 declare module '@theme/IconLanguage' {
@@ -678,8 +692,7 @@ declare module '@theme/IconLanguage' {
 
   export interface Props extends ComponentProps<'svg'> {}
 
-  const IconLanguage: (props: Props) => JSX.Element;
-  export default IconLanguage;
+  export default function IconLanguage(props: Props): JSX.Element;
 }
 
 declare module '@theme/IconExternalLink' {
@@ -687,8 +700,7 @@ declare module '@theme/IconExternalLink' {
 
   export interface Props extends ComponentProps<'svg'> {}
 
-  const IconExternalLink: (props: Props) => JSX.Element;
-  export default IconExternalLink;
+  export default function IconExternalLink(props: Props): JSX.Element;
 }
 
 declare module '@theme/TagsListByLetter' {
@@ -727,3 +739,17 @@ declare module '@theme/prism-include-languages' {
     PrismObject: typeof PrismNamespace,
   ): void;
 }
+
+declare module '@theme/Seo' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly title?: string;
+    readonly description?: string;
+    readonly keywords?: readonly string[] | string;
+    readonly image?: string;
+    readonly children?: ReactNode;
+  }
+
+  export default function Seo(props: Props): JSX.Element;
+}