@docusaurus/theme-classic 2.0.0-beta.18 → 2.0.0-beta.19

package/src/theme-classic.d.ts

@@ -5,10 +5,32 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/* eslint-disable @typescript-eslint/triple-slash-reference */
+
+/// <reference types="@docusaurus/module-type-aliases" />
+/// <reference types="@docusaurus/plugin-content-docs" />
+/// <reference types="@docusaurus/plugin-content-blog" />
+/// <reference types="@docusaurus/plugin-content-pages" />
+
+// This file, like all the other ambient declaration files for plugins, is
+// needed for TS to understand our `@theme` alias. The export signatures are
+// duplicated from the implementation, which is fine, since every module only
+// default-exports a React component.
+// TODO we'll eventually migrate to TS `paths` option. This is not easy due to
+// our theme shadowing—we probably need the user to specify multiple theme paths
+// in their tsconfig.
+
 declare module '@docusaurus/theme-classic' {
+  import type {LoadContext, Plugin} from '@docusaurus/types';
+
   export type Options = {
     customCss?: string | string[];
   };
+
+  export default function themeClassic(
+    context: LoadContext,
+    options: Options,
+  ): Plugin<undefined>;
 }
 
 declare module '@theme/Admonition' {
@@ -32,21 +54,41 @@ declare module '@theme/BackToTopButton' {
 }
 
 declare module '@theme/BlogListPaginator' {
-  import type {Metadata} from '@theme/BlogListPage';
+  import type {BlogPaginatedMetadata} from '@docusaurus/plugin-content-blog';
 
   export interface Props {
-    readonly metadata: Metadata;
+    readonly metadata: BlogPaginatedMetadata;
   }
   export default function BlogListPaginator(props: Props): JSX.Element;
 }
 
-declare module '@theme/BlogSidebar' {
+declare module '@theme/BlogSidebar/Desktop' {
   import type {BlogSidebar} from '@docusaurus/plugin-content-blog';
 
   export interface Props {
     readonly sidebar: BlogSidebar;
   }
 
+  export default function BlogSidebarDesktop(props: Props): JSX.Element;
+}
+
+declare module '@theme/BlogSidebar/Mobile' {
+  import type {BlogSidebar} from '@docusaurus/plugin-content-blog';
+
+  export interface Props {
+    readonly sidebar: BlogSidebar;
+  }
+
+  export default function BlogSidebarMobile(props: Props): JSX.Element;
+}
+
+declare module '@theme/BlogSidebar' {
+  import type {BlogSidebar} from '@docusaurus/plugin-content-blog';
+
+  export interface Props {
+    readonly sidebar?: BlogSidebar;
+  }
+
   export default function BlogSidebar(props: Props): JSX.Element;
 }
 
@@ -113,14 +155,15 @@ declare module '@theme/BlogLayout' {
 }
 
 declare module '@theme/CodeBlock' {
-  import type {ReactElement} from 'react';
+  import type {ReactNode} from 'react';
 
   export interface Props {
-    readonly children: string | ReactElement;
+    readonly children: ReactNode;
     readonly className?: string;
     readonly metastring?: string;
     readonly title?: string;
     readonly language?: string;
+    readonly showLineNumbers?: boolean;
   }
 
   export default function CodeBlock(props: Props): JSX.Element;
@@ -129,11 +172,72 @@ declare module '@theme/CodeBlock' {
 declare module '@theme/CodeBlock/CopyButton' {
   export interface Props {
     readonly code: string;
+    readonly className?: string;
   }
 
   export default function CopyButton(props: Props): JSX.Element;
 }
 
+declare module '@theme/CodeBlock/Container' {
+  import type {ComponentProps} from 'react';
+
+  export default function CodeBlockContainer<T extends 'div' | 'pre'>({
+    as: As,
+    ...props
+  }: {as: T} & ComponentProps<T>): JSX.Element;
+}
+
+declare module '@theme/CodeBlock/Content/Element' {
+  import type {Props} from '@theme/CodeBlock';
+
+  export type {Props};
+
+  export default function CodeBlockElementContent(props: Props): JSX.Element;
+}
+
+declare module '@theme/CodeBlock/Content/String' {
+  import type {Props as CodeBlockProps} from '@theme/CodeBlock';
+
+  export interface Props extends Omit<CodeBlockProps, 'children'> {
+    readonly children: string;
+  }
+
+  export default function CodeBlockStringContent(props: Props): JSX.Element;
+}
+
+declare module '@theme/CodeBlock/Line' {
+  import type {ComponentProps} from 'react';
+  import type Highlight from 'prism-react-renderer';
+
+  // Lib does not make this easy
+  type RenderProps = Parameters<
+    ComponentProps<typeof Highlight>['children']
+  >[0];
+  type GetLineProps = RenderProps['getLineProps'];
+  type GetTokenProps = RenderProps['getTokenProps'];
+  type Token = RenderProps['tokens'][number][number];
+
+  export interface Props {
+    readonly line: Token[];
+    readonly classNames: string[] | undefined;
+    readonly showLineNumbers: boolean;
+    readonly getLineProps: GetLineProps;
+    readonly getTokenProps: GetTokenProps;
+  }
+
+  export default function CodeBlockLine(props: Props): JSX.Element;
+}
+
+declare module '@theme/CodeBlock/WordWrapButton' {
+  export interface Props {
+    readonly className?: string;
+    readonly onClick: React.MouseEventHandler;
+    readonly isEnabled: boolean;
+  }
+
+  export default function WordWrapButton(props: Props): JSX.Element;
+}
+
 declare module '@theme/DocCard' {
   import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 
@@ -149,6 +253,7 @@ declare module '@theme/DocCardList' {
 
   export interface Props {
     readonly items: PropSidebarItem[];
+    readonly className?: string;
   }
 
   export default function DocCardList(props: Props): JSX.Element;
@@ -160,6 +265,50 @@ declare module '@theme/DocItemFooter' {
   export default function DocItemFooter(props: Props): JSX.Element;
 }
 
+declare module '@theme/DocPage/Layout' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+
+  export default function DocPageLayout(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocPage/Layout/Sidebar' {
+  import type {Dispatch, SetStateAction} from 'react';
+  import type {PropSidebar} from '@docusaurus/plugin-content-docs';
+
+  export interface Props {
+    readonly sidebar: PropSidebar;
+    readonly hiddenSidebarContainer: boolean;
+    readonly setHiddenSidebarContainer: Dispatch<SetStateAction<boolean>>;
+  }
+
+  export default function DocPageLayoutSidebar(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocPage/Layout/Sidebar/ExpandButton' {
+  export interface Props {
+    toggleSidebar: () => void;
+  }
+
+  export default function DocPageLayoutSidebarExpandButton(
+    props: Props,
+  ): JSX.Element;
+}
+
+declare module '@theme/DocPage/Layout/Main' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly hiddenSidebarContainer: boolean;
+    readonly children: ReactNode;
+  }
+
+  export default function DocPageLayoutMain(props: Props): JSX.Element;
+}
+
 declare module '@theme/DocPaginator' {
   import type {PropNavigation} from '@docusaurus/plugin-content-docs';
 
@@ -214,7 +363,7 @@ declare module '@theme/DocSidebar/Desktop/Content' {
 
 declare module '@theme/DocSidebar/Desktop/CollapseButton' {
   export interface Props {
-    onClick: React.MouseEventHandler;
+    readonly onClick: React.MouseEventHandler;
   }
 
   export default function CollapseButton(props: Props): JSX.Element;
@@ -235,6 +384,40 @@ declare module '@theme/DocSidebarItem' {
   export default function DocSidebarItem(props: Props): JSX.Element;
 }
 
+declare module '@theme/DocSidebarItem/Link' {
+  import type {Props as DocSidebarItemProps} from '@theme/DocSidebarItem';
+
+  import type {PropSidebarItemLink} from '@docusaurus/plugin-content-docs';
+
+  export interface Props extends DocSidebarItemProps {
+    readonly item: PropSidebarItemLink;
+  }
+
+  export default function DocSidebarItemLink(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocSidebarItem/Html' {
+  import type {Props as DocSidebarItemProps} from '@theme/DocSidebarItem';
+  import type {PropSidebarItemHtml} from '@docusaurus/plugin-content-docs';
+
+  export interface Props extends DocSidebarItemProps {
+    readonly item: PropSidebarItemHtml;
+  }
+
+  export default function DocSidebarItemHtml(props: Props): JSX.Element;
+}
+
+declare module '@theme/DocSidebarItem/Category' {
+  import type {Props as DocSidebarItemProps} from '@theme/DocSidebarItem';
+  import type {PropSidebarItemCategory} from '@docusaurus/plugin-content-docs';
+
+  export interface Props extends DocSidebarItemProps {
+    readonly item: PropSidebarItemCategory;
+  }
+
+  export default function DocSidebarItemCategory(props: Props): JSX.Element;
+}
+
 declare module '@theme/DocSidebarItems' {
   import type {Props as DocSidebarItemProps} from '@theme/DocSidebarItem';
   import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
@@ -288,7 +471,7 @@ declare module '@theme/Footer/Logo' {
   import type {FooterLogo} from '@docusaurus/theme-common';
 
   export interface Props {
-    logo: FooterLogo;
+    readonly logo: FooterLogo;
   }
 
   export default function FooterLogo(props: Props): JSX.Element;
@@ -296,7 +479,7 @@ declare module '@theme/Footer/Logo' {
 
 declare module '@theme/Footer/Copyright' {
   export interface Props {
-    copyright: string;
+    readonly copyright: string;
   }
 
   export default function FooterCopyright(props: Props): JSX.Element;
@@ -306,7 +489,7 @@ declare module '@theme/Footer/LinkItem' {
   import type {FooterLinkItem} from '@docusaurus/theme-common';
 
   export interface Props {
-    item: FooterLinkItem;
+    readonly item: FooterLinkItem;
   }
 
   export default function FooterLinkItem(props: Props): JSX.Element;
@@ -316,10 +499,10 @@ declare module '@theme/Footer/Layout' {
   import type {ReactNode} from 'react';
 
   export interface Props {
-    style: 'light' | 'dark';
-    links: ReactNode;
-    logo: ReactNode;
-    copyright: ReactNode;
+    readonly style: 'light' | 'dark';
+    readonly links: ReactNode;
+    readonly logo: ReactNode;
+    readonly copyright: ReactNode;
   }
 
   export default function FooterLayout(props: Props): JSX.Element;
@@ -329,7 +512,7 @@ declare module '@theme/Footer/Links' {
   import type {Footer} from '@docusaurus/theme-common';
 
   export interface Props {
-    links: Footer['links'];
+    readonly links: Footer['links'];
   }
 
   export default function FooterLinks(props: Props): JSX.Element;
@@ -339,7 +522,7 @@ declare module '@theme/Footer/Links/MultiColumn' {
   import type {MultiColumnFooter} from '@docusaurus/theme-common';
 
   export interface Props {
-    columns: MultiColumnFooter['links'];
+    readonly columns: MultiColumnFooter['links'];
   }
 
   export default function FooterLinksMultiColumn(props: Props): JSX.Element;
@@ -349,7 +532,7 @@ declare module '@theme/Footer/Links/Simple' {
   import type {SimpleFooter} from '@docusaurus/theme-common';
 
   export interface Props {
-    links: SimpleFooter['links'];
+    readonly links: SimpleFooter['links'];
   }
 
   export default function FooterLinksSimple(props: Props): JSX.Element;
@@ -361,7 +544,7 @@ declare module '@theme/Heading' {
   type HeadingType = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 
   export interface Props extends ComponentProps<HeadingType> {
-    as: HeadingType;
+    readonly as: HeadingType;
   }
 
   export default function Heading(props: Props): JSX.Element;
@@ -507,7 +690,9 @@ declare module '@theme/MDXComponents' {
     readonly h4: (props: ComponentProps<'h4'>) => JSX.Element;
     readonly h5: (props: ComponentProps<'h5'>) => JSX.Element;
     readonly h6: (props: ComponentProps<'h6'>) => JSX.Element;
-  } & {[tagName: string]: ComponentType<unknown>};
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [tagName: string]: ComponentType<any>;
+  };
 
   const MDXComponents: MDXComponentsObject;
   export default MDXComponents;
@@ -561,9 +746,9 @@ declare module '@theme/Navbar/MobileSidebar/Layout' {
   import type {ReactNode} from 'react';
 
   interface Props {
-    header: ReactNode;
-    primaryMenu: ReactNode;
-    secondaryMenu: ReactNode;
+    readonly header: ReactNode;
+    readonly primaryMenu: ReactNode;
+    readonly secondaryMenu: ReactNode;
   }
 
   export default function NavbarMobileSidebarLayout(props: Props): JSX.Element;
@@ -585,6 +770,16 @@ declare module '@theme/Navbar/MobileSidebar/Header' {
   export default function NavbarMobileSidebarHeader(): JSX.Element;
 }
 
+declare module '@theme/Navbar/Search' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+
+  export default function NavbarSearch(props: Props): JSX.Element;
+}
+
 declare module '@theme/NavbarItem/DefaultNavbarItem' {
   import type {Props as NavbarNavLinkProps} from '@theme/NavbarItem/NavbarNavLink';
 
@@ -610,6 +805,7 @@ declare module '@theme/NavbarItem/NavbarNavLink' {
     readonly activeBaseRegex?: string;
     readonly exact?: boolean;
     readonly label?: ReactNode;
+    readonly html?: string;
     readonly prependBaseUrlToHref?: string;
   }
 
@@ -688,7 +884,9 @@ declare module '@theme/NavbarItem/DocNavbarItem' {
     readonly docsPluginId?: string;
   }
 
-  export default function DocsSidebarNavbarItem(props: Props): JSX.Element;
+  export default function DocsSidebarNavbarItem(
+    props: Props,
+  ): JSX.Element | null;
 }
 
 declare module '@theme/NavbarItem/DocSidebarNavbarItem' {
@@ -702,6 +900,47 @@ declare module '@theme/NavbarItem/DocSidebarNavbarItem' {
   export default function DocSidebarNavbarItem(props: Props): JSX.Element;
 }
 
+declare module '@theme/NavbarItem/HtmlNavbarItem' {
+  import type {Props as DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
+
+  export interface Props extends DefaultNavbarItemProps {
+    readonly value: string;
+  }
+
+  export default function HtmlNavbarItem(props: Props): JSX.Element;
+}
+
+declare module '@theme/NavbarItem/ComponentTypes' {
+  import type {ComponentType} from 'react';
+
+  import type DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
+  import type DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
+  import type LocaleDropdownNavbarItem from '@theme/NavbarItem/LocaleDropdownNavbarItem';
+  import type SearchNavbarItem from '@theme/NavbarItem/SearchNavbarItem';
+  import type HtmlNavbarItem from '@theme/NavbarItem/HtmlNavbarItem';
+  import type DocNavbarItem from '@theme/NavbarItem/DocNavbarItem';
+  import type DocSidebarNavbarItem from '@theme/NavbarItem/DocSidebarNavbarItem';
+  import type DocsVersionNavbarItem from '@theme/NavbarItem/DocsVersionNavbarItem';
+  import type DocsVersionDropdownNavbarItem from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
+
+  export type ComponentTypesObject = {
+    readonly default: typeof DefaultNavbarItem;
+    readonly localeDropdown: typeof LocaleDropdownNavbarItem;
+    readonly search: typeof SearchNavbarItem;
+    readonly dropdown: typeof DropdownNavbarItem;
+    readonly html: typeof HtmlNavbarItem;
+    readonly doc: typeof DocNavbarItem;
+    readonly docSidebar: typeof DocSidebarNavbarItem;
+    readonly docsVersion: typeof DocsVersionNavbarItem;
+    readonly docsVersionDropdown: typeof DocsVersionDropdownNavbarItem;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [customComponentType: string]: ComponentType<any>;
+  };
+
+  const ComponentTypes: ComponentTypesObject;
+  export default ComponentTypes;
+}
+
 declare module '@theme/NavbarItem' {
   import type {ComponentProps} from 'react';
   import type {Props as DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
@@ -712,12 +951,14 @@ declare module '@theme/NavbarItem' {
   import type {Props as DocsVersionDropdownNavbarItemProps} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
   import type {Props as LocaleDropdownNavbarItemProps} from '@theme/NavbarItem/LocaleDropdownNavbarItem';
   import type {Props as SearchNavbarItemProps} from '@theme/NavbarItem/SearchNavbarItem';
+  import type {Props as HtmlNavbarItemProps} from '@theme/NavbarItem/HtmlNavbarItem';
 
   export type LinkLikeNavbarItemProps =
     | ({readonly type?: 'default'} & DefaultNavbarItemProps)
     | ({readonly type: 'doc'} & DocNavbarItemProps)
     | ({readonly type: 'docsVersion'} & DocsVersionNavbarItemProps)
-    | ({readonly type: 'docSidebar'} & DocSidebarNavbarItemProps);
+    | ({readonly type: 'docSidebar'} & DocSidebarNavbarItemProps)
+    | ({readonly type: 'html'} & HtmlNavbarItemProps);
 
   export type Props = ComponentProps<'a'> & {
     readonly position?: 'left' | 'right';
@@ -739,7 +980,14 @@ declare module '@theme/NavbarItem' {
 }
 
 declare module '@theme/NavbarItem/utils' {
-  export function getInfimaActiveClassName(mobile?: boolean): string;
+  /**
+   * On desktop and mobile, we would apply different class names for dropdown
+   * items.
+   * @see https://github.com/facebook/docusaurus/pull/5431
+   */
+  export function getInfimaActiveClassName(
+    mobile?: boolean,
+  ): `${'menu' | 'navbar'}__link--active`;
 }
 
 declare module '@theme/PaginatorNavLink' {
@@ -749,6 +997,7 @@ declare module '@theme/PaginatorNavLink' {
   export interface Props extends Omit<PropNavigationLink, 'title'> {
     readonly title: ReactNode;
     readonly subLabel?: JSX.Element;
+    readonly isNext?: boolean;
   }
 
   export default function PaginatorNavLink(props: Props): JSX.Element;
@@ -809,14 +1058,14 @@ declare module '@theme/ThemedImage' {
 }
 
 declare module '@theme/Details' {
-  import {Details, type DetailsProps} from '@docusaurus/theme-common';
+  import {Details, type DetailsProps} from '@docusaurus/theme-common/Details';
 
   export interface Props extends DetailsProps {}
   export default Details;
 }
 
 declare module '@theme/TOCItems' {
-  import type {TOCItem} from '@docusaurus/types';
+  import type {TOCItem} from '@docusaurus/mdx-loader';
 
   export interface Props {
     readonly toc: readonly TOCItem[];
@@ -830,11 +1079,24 @@ declare module '@theme/TOCItems' {
   export default function TOCItems(props: Props): JSX.Element;
 }
 
+declare module '@theme/TOCItems/Tree' {
+  import type {TOCTreeNode} from '@docusaurus/theme-common';
+
+  export interface Props {
+    readonly toc: readonly TOCTreeNode[];
+    readonly className: string;
+    readonly linkClassName: string | null;
+    readonly isChild?: boolean;
+  }
+
+  export default function TOCItems(props: Props): JSX.Element;
+}
+
 declare module '@theme/TOC' {
-  import type {TOCItem} from '@docusaurus/types';
+  import type {TOCItem} from '@docusaurus/mdx-loader';
 
-  // minHeadingLevel only exists as a per-doc option, and won't have a default
-  // set by Joi. See TOC, TOCInline, TOCCollapsible for examples
+  // `minHeadingLevel` only comes from doc/post front matter, 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;
@@ -846,7 +1108,7 @@ declare module '@theme/TOC' {
 }
 
 declare module '@theme/TOCInline' {
-  import type {TOCItem} from '@docusaurus/types';
+  import type {TOCItem} from '@docusaurus/mdx-loader';
 
   export interface Props {
     readonly toc: readonly TOCItem[];
@@ -858,7 +1120,7 @@ declare module '@theme/TOCInline' {
 }
 
 declare module '@theme/TOCCollapsible' {
-  import type {TOCItem} from '@docusaurus/types';
+  import type {TOCItem} from '@docusaurus/mdx-loader';
 
   export interface Props {
     readonly className?: string;
@@ -870,6 +1132,18 @@ declare module '@theme/TOCCollapsible' {
   export default function TOCCollapsible(props: Props): JSX.Element;
 }
 
+declare module '@theme/TOCCollapsible/CollapseButton' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'button'> {
+    collapsed: boolean;
+  }
+
+  export default function TOCCollapsibleCollapseButton(
+    props: Props,
+  ): JSX.Element;
+}
+
 declare module '@theme/ColorModeToggle' {
   import type {ColorMode} from '@docusaurus/theme-common';
 
@@ -921,6 +1195,14 @@ declare module '@theme/IconEdit' {
   export default function IconEdit(props: Props): JSX.Element;
 }
 
+declare module '@theme/IconHome' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function IconHome(props: Props): JSX.Element;
+}
+
 declare module '@theme/IconLightMode' {
   import type {ComponentProps} from 'react';
 
@@ -962,7 +1244,7 @@ declare module '@theme/IconExternalLink' {
 }
 
 declare module '@theme/TagsListByLetter' {
-  import type {TagsListItem} from '@docusaurus/theme-common';
+  import type {TagsListItem} from '@docusaurus/utils';
 
   export interface Props {
     readonly tags: readonly TagsListItem[];
@@ -980,7 +1262,7 @@ declare module '@theme/TagsListInline' {
 }
 
 declare module '@theme/Tag' {
-  import type {TagsListItem} from '@docusaurus/theme-common';
+  import type {TagsListItem} from '@docusaurus/utils';
   import type {Optional} from 'utility-types';
 
   export interface Props extends Optional<TagsListItem, 'count'> {}