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

package/src/theme-classic.d.ts

@@ -6,7 +6,21 @@
  */
 
 declare module '@docusaurus/theme-classic' {
-  export type Options = Partial<import('./index').PluginOptions>;
+  export type Options = {
+    customCss?: string | string[];
+  };
+}
+
+declare module '@theme/Admonition' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+    readonly type: 'note' | 'tip' | 'danger' | 'info' | 'caution';
+    readonly icon?: ReactNode;
+    readonly title?: string;
+  }
+  export default function Admonition(props: Props): JSX.Element;
 }
 
 declare module '@theme/AnnouncementBar' {
@@ -30,7 +44,8 @@ declare module '@theme/BlogListPaginator' {
 }
 
 declare module '@theme/BlogPostItem' {
-  import type {FrontMatter, Assets, Metadata} from '@theme/BlogPostPage';
+  import type {FrontMatter, Metadata} from '@theme/BlogPostPage';
+  import type {Assets} from '@docusaurus/plugin-content-blog';
 
   export interface Props {
     readonly frontMatter: FrontMatter;
@@ -56,7 +71,8 @@ declare module '@theme/BlogPostAuthor' {
 }
 
 declare module '@theme/BlogPostAuthors' {
-  import type {Metadata, Assets} from '@theme/BlogPostPage';
+  import type {Metadata} from '@theme/BlogPostPage';
+  import type {Assets} from '@docusaurus/plugin-content-blog';
 
   export interface Props {
     readonly authors: Metadata['authors'];
@@ -93,13 +109,14 @@ declare module '@theme/BlogLayout' {
 }
 
 declare module '@theme/CodeBlock' {
-  import {ReactElement} from 'react';
+  import type {ReactElement} from 'react';
 
   export interface Props {
     readonly children: string | ReactElement;
     readonly className?: string;
     readonly metastring?: string;
     readonly title?: string;
+    readonly language?: string;
   }
 
   const CodeBlock: (props: Props) => JSX.Element;
@@ -109,13 +126,10 @@ declare module '@theme/CodeBlock' {
 declare module '@theme/DocPaginator' {
   import type {PropNavigation} from '@docusaurus/plugin-content-docs';
 
-  type PageInfo = {readonly permalink: string; readonly title: string};
-
   // May be simpler to provide a {navigation: PropNavigation} prop?
   export interface Props extends PropNavigation {}
 
-  const DocPaginator: (props: Props) => JSX.Element;
-  export default DocPaginator;
+  export default function DocPaginator(props: Props): JSX.Element;
 }
 
 declare module '@theme/DocSidebar' {
@@ -137,23 +151,27 @@ declare module '@theme/DocSidebar' {
 declare module '@theme/DocSidebarItem' {
   import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 
-  type DocSidebarPropsBase = {
+  export interface Props {
     readonly activePath: string;
     readonly onItemClick?: (item: PropSidebarItem) => void;
     readonly level: number;
     readonly tabIndex?: number;
-  };
-
-  export interface Props extends DocSidebarPropsBase {
     readonly item: PropSidebarItem;
+    readonly index: number;
   }
-  const DocSidebarItem: (props: Props) => JSX.Element;
-  export default DocSidebarItem;
 
-  export type DocSidebarItemsProps = DocSidebarPropsBase & {
+  export default function DocSidebarItem(props: Props): JSX.Element;
+}
+
+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'> & {
     readonly items: readonly PropSidebarItem[];
   };
-  export const DocSidebarItems: (props: DocSidebarItemsProps) => JSX.Element;
+
+  export default function DocSidebarItems(props: Props): JSX.Element;
 }
 
 declare module '@theme/DocVersionSuggestions' {
@@ -170,7 +188,7 @@ declare module '@theme/EditThisPage' {
 }
 
 declare module '@theme/ErrorPageContent' {
-  import ErrorComponent from '@theme/Error';
+  import type ErrorComponent from '@theme/Error';
 
   const ErrorPageContent: typeof ErrorComponent;
   export default ErrorPageContent;
@@ -184,111 +202,20 @@ declare module '@theme/Footer' {
 declare module '@theme/Heading' {
   import type {ComponentProps} from 'react';
 
-  export type HeadingType = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
-  export interface Props extends ComponentProps<HeadingType> {}
-
-  const Heading: (Tag: HeadingType) => (props: Props) => JSX.Element;
-  export default Heading;
-  export const MainHeading: (props: Props) => JSX.Element;
-}
-
-declare module '@theme/hooks/useHideableNavbar' {
-  export type useHideableNavbarReturns = {
-    readonly navbarRef: (node: HTMLElement | null) => void;
-    readonly isNavbarVisible: boolean;
-  };
-
-  const useHideableNavbar: (hideOnScroll: boolean) => useHideableNavbarReturns;
-  export default useHideableNavbar;
-}
-
-declare module '@theme/hooks/useLocationHash' {
-  import type {Dispatch, SetStateAction} from 'react';
-
-  export type useLocationHashReturns = readonly [
-    string,
-    Dispatch<SetStateAction<string>>,
-  ];
-
-  const useLocationHash: (initialHash: string) => useLocationHashReturns;
-  export default useLocationHash;
-}
-
-declare module '@theme/hooks/useLockBodyScroll' {
-  const useLockBodyScroll: (lock?: boolean) => void;
-  export default useLockBodyScroll;
-}
-
-declare module '@theme/hooks/usePrismTheme' {
-  import defaultTheme from 'prism-react-renderer/themes/palenight';
-
-  const usePrismTheme: () => typeof defaultTheme;
-  export default usePrismTheme;
-}
-
-declare module '@theme/hooks/useTabGroupChoice' {
-  export type useTabGroupChoiceReturns = {
-    readonly tabGroupChoices: {readonly [groupId: string]: string};
-    readonly setTabGroupChoices: (groupId: string, newChoice: string) => void;
-  };
-
-  const useTabGroupChoice: () => useTabGroupChoiceReturns;
-  export default useTabGroupChoice;
-}
-
-declare module '@theme/hooks/useTheme' {
-  export type useThemeReturns = {
-    readonly isDarkTheme: boolean;
-    readonly setLightTheme: () => void;
-    readonly setDarkTheme: () => void;
-  };
-
-  const useTheme: () => useThemeReturns;
-  export default useTheme;
-}
-
-declare module '@theme/hooks/useThemeContext' {
-  export type ThemeContextProps = {
-    isDarkTheme: boolean;
-    setLightTheme: () => void;
-    setDarkTheme: () => void;
-  };
-
-  export default function useThemeContext(): ThemeContextProps;
-}
-
-declare module '@theme/hooks/useUserPreferencesContext' {
-  export type UserPreferencesContextProps = {
-    tabGroupChoices: {readonly [groupId: string]: string};
-    setTabGroupChoices: (groupId: string, newChoice: string) => void;
-  };
-
-  export default function useUserPreferencesContext(): UserPreferencesContextProps;
-}
+  type HeadingType = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
 
-declare module '@theme/hooks/useWindowSize' {
-  export const windowSizes: {
-    desktop: 'desktop';
-    mobile: 'mobile';
-    ssr: 'ssr';
-  };
-
-  export type WindowSize = keyof typeof windowSizes;
-
-  export default function useWindowSize(): WindowSize;
-}
-
-declare module '@theme/hooks/useKeyboardNavigation' {
-  const useKeyboardNavigation: () => void;
+  export interface Props extends ComponentProps<HeadingType> {
+    as: HeadingType;
+  }
 
-  export default useKeyboardNavigation;
+  export default function Heading(props: Props): JSX.Element;
 }
 
 declare module '@theme/Layout' {
   import type {ReactNode} from 'react';
 
   export interface Props {
-    readonly children: ReactNode;
+    readonly children?: ReactNode;
     readonly title?: string;
     readonly noFooter?: boolean;
     readonly description?: string;
@@ -303,8 +230,7 @@ declare module '@theme/Layout' {
     };
   }
 
-  const Layout: (props: Props) => JSX.Element;
-  export default Layout;
+  export default function Layout(props: Props): JSX.Element;
 }
 
 declare module '@theme/LayoutHead' {
@@ -312,8 +238,17 @@ declare module '@theme/LayoutHead' {
 
   export interface Props extends Omit<LayoutProps, 'children'> {}
 
-  const LayoutHead: (props: Props) => JSX.Element;
-  export default LayoutHead;
+  export default function LayoutHead(props: Props): JSX.Element;
+}
+
+declare module '@theme/LayoutProviders' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+  }
+
+  export default function LayoutProviders(props: Props): JSX.Element;
 }
 
 declare module '@theme/SearchMetadata' {
@@ -372,18 +307,9 @@ declare module '@theme/Navbar' {
 }
 
 declare module '@theme/NavbarItem/DefaultNavbarItem' {
-  import type {ReactNode} from 'react';
-  import type {LinkProps} from '@docusaurus/Link';
+  import type {Props as NavbarNavLinkProps} from '@theme/NavbarItem/NavbarNavLink';
 
-  export type NavLinkProps = LinkProps & {
-    readonly activeBasePath?: string;
-    readonly activeBaseRegex?: string;
-    readonly exact?: boolean;
-    readonly label?: ReactNode;
-    readonly prependBaseUrlToHref?: string;
-  };
-
-  export type DesktopOrMobileNavBarItemProps = NavLinkProps & {
+  export type DesktopOrMobileNavBarItemProps = NavbarNavLinkProps & {
     readonly isDropdownItem?: boolean;
     readonly className?: string;
     readonly position?: 'left' | 'right';
@@ -393,17 +319,30 @@ declare module '@theme/NavbarItem/DefaultNavbarItem' {
     readonly mobile?: boolean;
   }
 
-  export const NavLink: (props: NavLinkProps) => JSX.Element;
+  export default function DefaultNavbarItem(props: Props): JSX.Element;
+}
+
+declare module '@theme/NavbarItem/NavbarNavLink' {
+  import type {ReactNode} from 'react';
+  import type {LinkProps} from '@docusaurus/Link';
+
+  export type Props = LinkProps & {
+    readonly activeBasePath?: string;
+    readonly activeBaseRegex?: string;
+    readonly exact?: boolean;
+    readonly label?: ReactNode;
+    readonly prependBaseUrlToHref?: string;
+  };
 
-  const DefaultNavbarItem: (props: Props) => JSX.Element;
-  export default DefaultNavbarItem;
+  export default function NavbarNavLink(props: Props): JSX.Element;
 }
 
 declare module '@theme/NavbarItem/DropdownNavbarItem' {
-  import type {NavLinkProps} from '@theme/NavbarItem/DefaultNavbarItem';
+  import type {Props as NavbarNavLinkProps} from '@theme/NavbarItem/NavbarNavLink';
+
   import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 
-  export type DesktopOrMobileNavBarItemProps = NavLinkProps & {
+  export type DesktopOrMobileNavBarItemProps = NavbarNavLinkProps & {
     readonly position?: 'left' | 'right';
     readonly items: readonly LinkLikeNavbarItemProps[];
     readonly className?: string;
@@ -477,10 +416,23 @@ declare module '@theme/NavbarItem/DocNavbarItem' {
   export default DocsSidebarNavbarItem;
 }
 
+declare module '@theme/NavbarItem/DocSidebarNavbarItem' {
+  import type {Props as DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
+
+  export interface Props extends DefaultNavbarItemProps {
+    readonly sidebarId: string;
+    readonly docsPluginId?: string;
+  }
+
+  const DocSidebarNavbarItem: (props: Props) => JSX.Element;
+  export default DocSidebarNavbarItem;
+}
+
 declare module '@theme/NavbarItem' {
   import type {ComponentProps} from 'react';
   import type {Props as DefaultNavbarItemProps} from '@theme/NavbarItem/DefaultNavbarItem';
   import type {Props as DocNavbarItemProps} from '@theme/NavbarItem/DocNavbarItem';
+  import type {Props as DocSidebarNavbarItemProps} from '@theme/NavbarItem/DocSidebarNavbarItem';
   import type {Props as DocsVersionNavbarItemProps} from '@theme/NavbarItem/DocsVersionNavbarItem';
   import type {Props as DropdownNavbarItemProps} from '@theme/NavbarItem/DropdownNavbarItem';
   import type {Props as DocsVersionDropdownNavbarItemProps} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
@@ -490,7 +442,8 @@ declare module '@theme/NavbarItem' {
   export type LinkLikeNavbarItemProps =
     | ({readonly type?: 'default'} & DefaultNavbarItemProps)
     | ({readonly type: 'doc'} & DocNavbarItemProps)
-    | ({readonly type: 'docsVersion'} & DocsVersionNavbarItemProps);
+    | ({readonly type: 'docsVersion'} & DocsVersionNavbarItemProps)
+    | ({readonly type: 'docSidebar'} & DocSidebarNavbarItemProps);
 
   export type Props = ComponentProps<'a'> & {
     readonly position?: 'left' | 'right';
@@ -512,6 +465,22 @@ declare module '@theme/NavbarItem' {
   export default NavbarItem;
 }
 
+declare module '@theme/NavbarItem/utils' {
+  export function getInfimaActiveClassName(mobile?: boolean): string;
+}
+
+declare module '@theme/PaginatorNavLink' {
+  import type {ReactNode} from 'react';
+  import type {PropNavigationLink} from '@docusaurus/plugin-content-docs';
+
+  export interface Props extends Omit<PropNavigationLink, 'title'> {
+    readonly title: ReactNode;
+    readonly subLabel?: JSX.Element;
+  }
+
+  export default function PaginatorNavLink(props: Props): JSX.Element;
+}
+
 declare module '@theme/SearchBar' {
   export default function SearchBar(): JSX.Element;
 }
@@ -526,6 +495,7 @@ declare module '@theme/TabItem' {
     readonly label?: string;
     readonly hidden?: boolean;
     readonly className?: string;
+    readonly attributes?: Record<string, unknown>;
   }
 
   const TabItem: (props: Props) => JSX.Element;
@@ -541,7 +511,11 @@ declare module '@theme/Tabs' {
     readonly block?: boolean;
     readonly children: readonly ReactElement<TabItemProps>[];
     readonly defaultValue?: string | null;
-    readonly values?: readonly {value: string; label?: string}[];
+    readonly values?: readonly {
+      value: string;
+      label?: string;
+      attributes?: Record<string, unknown>;
+    }[];
     readonly groupId?: string;
     readonly className?: string;
   }
@@ -565,23 +539,12 @@ declare module '@theme/ThemedImage' {
 }
 
 declare module '@theme/Details' {
-  import {Details, DetailsProps} from '@docusaurus/theme-common';
+  import {Details, type DetailsProps} from '@docusaurus/theme-common';
 
   export interface Props extends DetailsProps {}
   export default Details;
 }
 
-declare module '@theme/ThemeProvider' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    readonly children: ReactNode;
-  }
-
-  const ThemeProvider: (props: Props) => JSX.Element;
-  export default ThemeProvider;
-}
-
 declare module '@theme/TOCItems' {
   import type {TOCItem} from '@docusaurus/types';
 
@@ -662,46 +625,6 @@ declare module '@theme/Toggle' {
   export default Toggle;
 }
 
-declare module '@theme/UserPreferencesProvider' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    readonly children: ReactNode;
-  }
-
-  const UserPreferencesProvider: (props: Props) => JSX.Element;
-  export default UserPreferencesProvider;
-}
-
-declare module '@theme/LayoutProviders' {
-  import type {ReactNode} from 'react';
-
-  export interface Props {
-    readonly children: ReactNode;
-  }
-
-  const LayoutProviders: (props: Props) => JSX.Element;
-  export default LayoutProviders;
-}
-
-declare module '@theme/ThemeContext' {
-  import type {Context} from 'react';
-  import type {ThemeContextProps} from '@theme/hooks/useThemeContext';
-
-  const ThemeContext: Context<ThemeContextProps | undefined>;
-  export default ThemeContext;
-}
-
-declare module '@theme/UserPreferencesContext' {
-  import type {Context} from 'react';
-  import type {UserPreferencesContextProps} from '@theme/hooks/useUserPreferencesContext';
-
-  const UserPreferencesContext: Context<
-    UserPreferencesContextProps | undefined
-  >;
-  export default UserPreferencesContext;
-}
-
 declare module '@theme/Logo' {
   import type {ComponentProps} from 'react';
 

package/src/translations.ts

@@ -5,12 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {TranslationFile, TranslationFileContent} from '@docusaurus/types';
-import {
+import type {TranslationFile, TranslationFileContent} from '@docusaurus/types';
+import type {
   ThemeConfig,
   Navbar,
   NavbarItem,
   Footer,
+  MultiColumnFooter,
+  SimpleFooter,
 } from '@docusaurus/theme-common';
 
 import {keyBy, chain} from 'lodash';
@@ -69,10 +71,17 @@ function translateNavbar(
   };
 }
 
+function isMultiColumnFooterLinks(
+  links: MultiColumnFooter['links'] | SimpleFooter['links'],
+): links is MultiColumnFooter['links'] {
+  return links.length > 0 && 'title' in links[0];
+}
+
 function getFooterTranslationFile(footer: Footer): TranslationFileContent {
-  // TODO POC code
   const footerLinkTitles: TranslationFileContent = chain(
-    footer.links.filter((link) => !!link.title),
+    isMultiColumnFooterLinks(footer.links)
+      ? footer.links.filter((link) => !!link.title)
+      : [],
   )
     .keyBy((link) => `link.title.${link.title}`)
     .mapValues((link) => ({
@@ -82,7 +91,11 @@ function getFooterTranslationFile(footer: Footer): TranslationFileContent {
     .value();
 
   const footerLinkLabels: TranslationFileContent = chain(
-    footer.links.flatMap((link) => link.items).filter((link) => !!link.label),
+    isMultiColumnFooterLinks(footer.links)
+      ? footer.links
+          .flatMap((link) => link.items)
+          .filter((link) => !!link.label)
+      : footer.links.filter((link) => !!link.label),
   )
     .keyBy((linkItem) => `link.item.label.${linkItem.label}`)
     .mapValues((linkItem) => ({
@@ -108,17 +121,24 @@ function translateFooter(
   footer: Footer,
   footerTranslations: TranslationFileContent,
 ): Footer {
-  const links = footer.links.map((link) => ({
-    ...link,
-    title:
-      footerTranslations[`link.title.${link.title}`]?.message ?? link.title,
-    items: link.items.map((linkItem) => ({
-      ...linkItem,
-      label:
-        footerTranslations[`link.item.label.${linkItem.label}`]?.message ??
-        linkItem.label,
-    })),
-  }));
+  const links = isMultiColumnFooterLinks(footer.links)
+    ? footer.links.map((link) => ({
+        ...link,
+        title:
+          footerTranslations[`link.title.${link.title}`]?.message ?? link.title,
+        items: link.items.map((linkItem) => ({
+          ...linkItem,
+          label:
+            footerTranslations[`link.item.label.${linkItem.label}`]?.message ??
+            linkItem.label,
+        })),
+      }))
+    : footer.links.map((link) => ({
+        ...link,
+        label:
+          footerTranslations[`link.item.label.${link.label}`]?.message ??
+          link.label,
+      }));
 
   const copyright = footerTranslations.copyright?.message ?? footer.copyright;
 

package/src/validateThemeConfig.ts

@@ -41,6 +41,7 @@ const DEFAULT_CONFIG = {
     items: [],
   },
   hideableSidebar: false,
+  autoCollapseSidebarCategories: false,
   tableOfContents: {
     minHeadingLevel: 2,
     maxHeadingLevel: 3,
@@ -85,6 +86,12 @@ const DocItemSchema = NavbarItemBaseSchema.append({
   docsPluginId: Joi.string(),
 });
 
+const DocSidebarItemSchema = NavbarItemBaseSchema.append({
+  type: Joi.string().equal('docSidebar').required(),
+  sidebarId: Joi.string().required(),
+  docsPluginId: Joi.string(),
+});
+
 const itemWithType = (type: string | undefined) => {
   // because equal(undefined) is not supported :/
   const typeSchema = type
@@ -172,6 +179,10 @@ const NavbarItemSchema = Joi.object({
       is: itemWithType('doc'),
       then: DocItemSchema,
     },
+    {
+      is: itemWithType('docSidebar'),
+      then: DocSidebarItemSchema,
+    },
     {
       is: itemWithType('localeDropdown'),
       then: LocaleDropdownNavbarItemSchema,
@@ -266,8 +277,10 @@ const ThemeConfigSchema = Joi.object({
   metadata: Joi.array()
     .items(HtmlMetadataSchema)
     .default(DEFAULT_CONFIG.metadata),
+  // cSpell:ignore metadatas
   metadatas: Joi.any().forbidden().messages({
     'any.unknown':
+      // cSpell:ignore metadatas
       'themeConfig.metadatas has been renamed as themeConfig.metadata. See https://github.com/facebook/docusaurus/pull/5871',
   }),
   announcementBar: Joi.object({
@@ -311,13 +324,18 @@ const ThemeConfigSchema = Joi.object({
       href: Joi.string(),
     }),
     copyright: Joi.string(),
-    links: Joi.array()
-      .items(
+    links: Joi.alternatives(
+      Joi.array().items(
         Joi.object({
-          title: Joi.string().allow(null),
+          title: Joi.string().allow(null).default(null),
           items: Joi.array().items(FooterLinkItemSchema).default([]),
         }),
-      )
+      ),
+      Joi.array().items(FooterLinkItemSchema),
+    )
+      .messages({
+        'alternatives.match': `The footer must be either simple or multi-column, and not a mix of the two. See: https://docusaurus.io/docs/api/themes/configuration#footer-links`,
+      })
       .default([]),
   }).optional(),
   prism: Joi.object({
@@ -337,6 +355,9 @@ const ThemeConfigSchema = Joi.object({
     .default(DEFAULT_CONFIG.prism)
     .unknown(),
   hideableSidebar: Joi.bool().default(DEFAULT_CONFIG.hideableSidebar),
+  autoCollapseSidebarCategories: Joi.bool().default(
+    DEFAULT_CONFIG.autoCollapseSidebarCategories,
+  ),
   sidebarCollapsible: Joi.forbidden().messages({
     'any.unknown':
       'The themeConfig.sidebarCollapsible has been moved to docs plugin options. See: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs',

package/babel.config.js

@@ -1,35 +0,0 @@
-/**
- * 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.
- */
-
-module.exports = {
-  env: {
-    // USED FOR NODE/RUNTIME
-    // maybe we should differenciate both cases because
-    // we mostly need to transpile some features so that node does not crash...
-    lib: {
-      presets: [
-        ['@babel/preset-typescript', {isTSX: true, allExtensions: true}],
-      ],
-      // Useful to transpile for older node versions
-      plugins: [
-        '@babel/plugin-transform-modules-commonjs',
-        '@babel/plugin-proposal-nullish-coalescing-operator',
-        '@babel/plugin-proposal-optional-chaining',
-      ],
-    },
-
-    // USED FOR JS SWIZZLE
-    // /lib-next folder is used as source to swizzle JS source code
-    // This JS code is created from TS source code
-    // This source code should look clean/human readable to be usable
-    'lib-next': {
-      presets: [
-        ['@babel/preset-typescript', {isTSX: true, allExtensions: true}],
-      ],
-    },
-  },
-};