refactor(theme-common): split package into public/internal API entrypoints (#7660)

* add theme-common/internal export

* Split @docusaurus/theme-common into public/internal apis

* fixes

* public <-> private

* public <-> private

* public <-> private

* fix

* add "removeThemeInternalReexport" CI script

* :s windows CI check not working: not that useful

* remove bad import

* refactors

* reorder

* make useBackToTopButton internal

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

.eslintrc.js

@@ -451,6 +451,7 @@ module.exports = {
         'admin/**',
         'jest/**',
         'website/**',
+        'packages/docusaurus-theme-common/removeThemeInternalReexport.mjs',
         'packages/docusaurus-theme-translations/update.mjs',
         'packages/docusaurus-theme-translations/src/utils.ts',
       ],

.github/workflows/tests.yml

@@ -40,3 +40,7 @@ jobs:
         run: yarn test
       - name: TypeCheck website
         run: yarn workspace website typecheck
+      - name: Remove Theme Internal Re-export
+        run: yarn workspace @docusaurus/theme-common removeThemeInternalReexport
+      - name: Docusaurus Build
+        run: yarn build:website:fast

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -1103,7 +1103,7 @@ declare module '@theme/TOCItems' {
 }
 
 declare module '@theme/TOCItems/Tree' {
-  import type {TOCTreeNode} from '@docusaurus/theme-common';
+  import type {TOCTreeNode} from '@docusaurus/theme-common/internal';
 
   export interface Props {
     readonly toc: readonly TOCTreeNode[];

packages/docusaurus-theme-classic/src/theme/AnnouncementBar/index.tsx

@@ -7,7 +7,8 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {useThemeConfig, useAnnouncementBar} from '@docusaurus/theme-common';
+import {useThemeConfig} from '@docusaurus/theme-common';
+import {useAnnouncementBar} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
 import IconClose from '@theme/IconClose';
 

packages/docusaurus-theme-classic/src/theme/BackToTopButton/index.tsx

@@ -8,7 +8,8 @@
 import React from 'react';
 import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
-import {ThemeClassNames, useBackToTopButton} from '@docusaurus/theme-common';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useBackToTopButton} from '@docusaurus/theme-common/internal';
 
 import styles from './styles.module.css';
 

packages/docusaurus-theme-classic/src/theme/CodeBlock/Container/index.tsx

@@ -7,11 +7,8 @@
 
 import React, {type ComponentProps} from 'react';
 import clsx from 'clsx';
-import {
+import {ThemeClassNames, usePrismTheme} from '@docusaurus/theme-common';
-  usePrismTheme,
+import {getPrismCssVariables} from '@docusaurus/theme-common/internal';
-  getPrismCssVariables,
-  ThemeClassNames,
-} from '@docusaurus/theme-common';
 import styles from './styles.module.css';
 
 export default function CodeBlockContainer<T extends 'div' | 'pre'>({

packages/docusaurus-theme-classic/src/theme/CodeBlock/Content/String.tsx

@@ -7,15 +7,14 @@
 
 import React from 'react';
 import clsx from 'clsx';
+import {useThemeConfig, usePrismTheme} from '@docusaurus/theme-common';
 import {
-  useThemeConfig,
   parseCodeBlockTitle,
   parseLanguage,
   parseLines,
   containsLineNumbers,
-  usePrismTheme,
   useCodeWordWrap,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import Highlight, {defaultProps, type Language} from 'prism-react-renderer';
 import Line from '@theme/CodeBlock/Line';
 import CopyButton from '@theme/CodeBlock/CopyButton';

packages/docusaurus-theme-classic/src/theme/DocBreadcrumbs/index.tsx

@@ -7,11 +7,11 @@
 
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import {
-  ThemeClassNames,
   useSidebarBreadcrumbs,
   useHomePageRoute,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import {translate} from '@docusaurus/Translate';

packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx

@@ -8,7 +8,10 @@
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
-import {findFirstCategoryLink, useDocById} from '@docusaurus/theme-common';
+import {
+  findFirstCategoryLink,
+  useDocById,
+} from '@docusaurus/theme-common/internal';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import {translate} from '@docusaurus/Translate';
 import type {Props} from '@theme/DocCard';

packages/docusaurus-theme-classic/src/theme/DocCardList/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {findFirstCategoryLink} from '@docusaurus/theme-common';
+import {findFirstCategoryLink} from '@docusaurus/theme-common/internal';
 import DocCard from '@theme/DocCard';
 import type {Props} from '@theme/DocCardList';
 import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';

packages/docusaurus-theme-classic/src/theme/DocItem/Content/index.tsx

@@ -7,7 +7,8 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
 import Heading from '@theme/Heading';
 import MDXContent from '@theme/MDXContent';
 import type {Props} from '@theme/DocItem/Content';

packages/docusaurus-theme-classic/src/theme/DocItem/Footer/index.tsx

@@ -7,11 +7,8 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {
+import {ThemeClassNames} from '@docusaurus/theme-common';
-  ThemeClassNames,
+import {useDoc, type DocContextValue} from '@docusaurus/theme-common/internal';
-  useDoc,
-  type DocContextValue,
-} from '@docusaurus/theme-common';
 import LastUpdated from '@theme/LastUpdated';
 import EditThisPage from '@theme/EditThisPage';
 import TagsListInline, {

packages/docusaurus-theme-classic/src/theme/DocItem/Layout/index.tsx

@@ -7,7 +7,8 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {useWindowSize, useDoc} from '@docusaurus/theme-common';
+import {useWindowSize} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
 import DocItemPaginator from '@theme/DocItem/Paginator';
 import DocVersionBanner from '@theme/DocVersionBanner';
 import DocVersionBadge from '@theme/DocVersionBadge';

packages/docusaurus-theme-classic/src/theme/DocItem/Metadata/index.tsx

@@ -6,7 +6,8 @@
  */
 
 import React from 'react';
-import {PageMetadata, useDoc} from '@docusaurus/theme-common';
+import {PageMetadata} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
 
 export default function DocItemMetadata(): JSX.Element {
   const {metadata, frontMatter, assets} = useDoc();

packages/docusaurus-theme-classic/src/theme/DocItem/Paginator/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import {useDoc} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
 import DocPaginator from '@theme/DocPaginator';
 
 /**

packages/docusaurus-theme-classic/src/theme/DocItem/TOC/Desktop/index.tsx

@@ -6,7 +6,8 @@
  */
 
 import React from 'react';
-import {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
 
 import TOC from '@theme/TOC';
 

packages/docusaurus-theme-classic/src/theme/DocItem/TOC/Mobile/index.tsx

@@ -7,7 +7,9 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {ThemeClassNames, useDoc} from '@docusaurus/theme-common';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDoc} from '@docusaurus/theme-common/internal';
+
 import TOCCollapsible from '@theme/TOCCollapsible';
 
 import styles from './styles.module.css';

packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx

@@ -6,7 +6,8 @@
  */
 
 import React from 'react';
-import {HtmlClassNameProvider, DocProvider} from '@docusaurus/theme-common';
+import {HtmlClassNameProvider} from '@docusaurus/theme-common';
+import {DocProvider} from '@docusaurus/theme-common/internal';
 import DocItemMetadata from '@theme/DocItem/Metadata';
 import DocItemLayout from '@theme/DocItem/Layout';
 import type {Props} from '@theme/DocItem';

packages/docusaurus-theme-classic/src/theme/DocPage/Layout/Main/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {useDocsSidebar} from '@docusaurus/theme-common';
+import {useDocsSidebar} from '@docusaurus/theme-common/internal';
 import type {Props} from '@theme/DocPage/Layout/Main';
 
 import styles from './styles.module.css';

packages/docusaurus-theme-classic/src/theme/DocPage/Layout/Sidebar/index.tsx

@@ -7,7 +7,8 @@
 
 import React, {type ReactNode, useState, useCallback} from 'react';
 import clsx from 'clsx';
-import {ThemeClassNames, useDocsSidebar} from '@docusaurus/theme-common';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDocsSidebar} from '@docusaurus/theme-common/internal';
 import {useLocation} from '@docusaurus/router';
 import DocSidebar from '@theme/DocSidebar';
 import ExpandButton from '@theme/DocPage/Layout/Sidebar/ExpandButton';

packages/docusaurus-theme-classic/src/theme/DocPage/Layout/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {useState} from 'react';
-import {useDocsSidebar} from '@docusaurus/theme-common';
+import {useDocsSidebar} from '@docusaurus/theme-common/internal';
 import Layout from '@theme/Layout';
 import BackToTopButton from '@theme/BackToTopButton';
 import DocPageLayoutSidebar from '@theme/DocPage/Layout/Sidebar';

packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx

@@ -7,14 +7,13 @@
 
 import React from 'react';
 import clsx from 'clsx';
+import {HtmlClassNameProvider, ThemeClassNames} from '@docusaurus/theme-common';
 import {
-  HtmlClassNameProvider,
-  ThemeClassNames,
   docVersionSearchTag,
   DocsSidebarProvider,
   DocsVersionProvider,
   useDocRouteMetadata,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import DocPageLayout from '@theme/DocPage/Layout';
 import NotFound from '@theme/NotFound';
 import SearchMetadata from '@theme/SearchMetadata';

packages/docusaurus-theme-classic/src/theme/DocSidebar/Desktop/Content/index.tsx

@@ -7,11 +7,11 @@
 
 import React, {useState} from 'react';
 import clsx from 'clsx';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import {
-  ThemeClassNames,
   useAnnouncementBar,
   useScrollPosition,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import DocSidebarItems from '@theme/DocSidebarItems';
 import type {Props} from '@theme/DocSidebar/Desktop/Content';
 

packages/docusaurus-theme-classic/src/theme/DocSidebar/Mobile/index.tsx

@@ -11,8 +11,8 @@ import {
   NavbarSecondaryMenuFiller,
   type NavbarSecondaryMenuComponent,
   ThemeClassNames,
-  useNavbarMobileSidebar,
 } from '@docusaurus/theme-common';
+import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
 import DocSidebarItems from '@theme/DocSidebarItems';
 import type {Props} from '@theme/DocSidebar/Mobile';
 

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Category/index.tsx

@@ -8,16 +8,18 @@
 import React, {type ComponentProps, useEffect, useMemo} from 'react';
 import clsx from 'clsx';
 import {
-  isActiveSidebarItem,
+  ThemeClassNames,
+  useThemeConfig,
   usePrevious,
   Collapsible,
   useCollapsible,
+} from '@docusaurus/theme-common';
+import {
+  isActiveSidebarItem,
   findFirstCategoryLink,
-  ThemeClassNames,
-  useThemeConfig,
   useDocSidebarItemsExpandedState,
   isSamePath,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
 import {translate} from '@docusaurus/Translate';
 import useIsBrowser from '@docusaurus/useIsBrowser';

packages/docusaurus-theme-classic/src/theme/DocSidebarItem/Link/index.tsx

@@ -7,7 +7,8 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {isActiveSidebarItem, ThemeClassNames} from '@docusaurus/theme-common';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {isActiveSidebarItem} from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import IconExternalLink from '@theme/IconExternalLink';

packages/docusaurus-theme-classic/src/theme/DocSidebarItems/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {memo} from 'react';
-import {DocSidebarItemsExpandedStateProvider} from '@docusaurus/theme-common';
+import {DocSidebarItemsExpandedStateProvider} from '@docusaurus/theme-common/internal';
 import DocSidebarItem from '@theme/DocSidebarItem';
 
 import type {Props} from '@theme/DocSidebarItems';

packages/docusaurus-theme-classic/src/theme/DocVersionBadge/index.tsx

@@ -8,7 +8,8 @@
 import React from 'react';
 import clsx from 'clsx';
 import Translate from '@docusaurus/Translate';
-import {ThemeClassNames, useDocsVersion} from '@docusaurus/theme-common';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDocsVersion} from '@docusaurus/theme-common/internal';
 import type {Props} from '@theme/DocVersionBadge';
 
 export default function DocVersionBadge({

packages/docusaurus-theme-classic/src/theme/DocVersionBanner/index.tsx

@@ -15,12 +15,11 @@ import {
   useDocVersionSuggestions,
   type GlobalVersion,
 } from '@docusaurus/plugin-content-docs/client';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import {
-  ThemeClassNames,
   useDocsPreferredVersion,
   useDocsVersion,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
-
 import type {Props} from '@theme/DocVersionBanner';
 import type {
   VersionBanner,

packages/docusaurus-theme-classic/src/theme/Layout/index.tsx

@@ -8,11 +8,8 @@
 import React from 'react';
 import clsx from 'clsx';
 import ErrorBoundary from '@docusaurus/ErrorBoundary';
-import {
+import {PageMetadata, ThemeClassNames} from '@docusaurus/theme-common';
-  PageMetadata,
+import {useKeyboardNavigation} from '@docusaurus/theme-common/internal';
-  ThemeClassNames,
-  useKeyboardNavigation,
-} from '@docusaurus/theme-common';
 import SkipToContent from '@theme/SkipToContent';
 import AnnouncementBar from '@theme/AnnouncementBar';
 import Navbar from '@theme/Navbar';

packages/docusaurus-theme-classic/src/theme/LayoutProviders/index.tsx

@@ -14,7 +14,7 @@ import {
   ScrollControllerProvider,
   NavbarProvider,
   PluginHtmlClassNameProvider,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import type {Props} from '@theme/LayoutProviders';
 
 export default function LayoutProviders({children}: Props): JSX.Element {

packages/docusaurus-theme-classic/src/theme/Navbar/Content/index.tsx

@@ -6,11 +6,11 @@
  */
 
 import React, {type ReactNode} from 'react';
+import {useThemeConfig} from '@docusaurus/theme-common';
 import {
   splitNavbarItems,
   useNavbarMobileSidebar,
-  useThemeConfig,
+} from '@docusaurus/theme-common/internal';
-} from '@docusaurus/theme-common';
 import NavbarItem, {type Props as NavbarItemConfig} from '@theme/NavbarItem';
 import NavbarColorModeToggle from '@theme/Navbar/ColorModeToggle';
 import SearchBar from '@theme/SearchBar';

packages/docusaurus-theme-classic/src/theme/Navbar/Layout/index.tsx

@@ -7,11 +7,11 @@
 
 import React, {type ComponentProps} from 'react';
 import clsx from 'clsx';
+import {useThemeConfig} from '@docusaurus/theme-common';
 import {
-  useThemeConfig,
   useHideableNavbar,
   useNavbarMobileSidebar,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import NavbarMobileSidebar from '@theme/Navbar/MobileSidebar';
 import type {Props} from '@theme/Navbar/Layout';
 

packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/Header/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import {useNavbarMobileSidebar} from '@docusaurus/theme-common';
+import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
 import NavbarColorModeToggle from '@theme/Navbar/ColorModeToggle';
 import IconClose from '@theme/IconClose';
 import NavbarLogo from '@theme/Navbar/Logo';

packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/Layout/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {useNavbarSecondaryMenu} from '@docusaurus/theme-common';
+import {useNavbarSecondaryMenu} from '@docusaurus/theme-common/internal';
 import type {Props} from '@theme/Navbar/MobileSidebar/Layout';
 
 export default function NavbarMobileSidebarLayout({

packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/PrimaryMenu/index.tsx

@@ -6,7 +6,8 @@
  */
 
 import React from 'react';
-import {useNavbarMobileSidebar, useThemeConfig} from '@docusaurus/theme-common';
+import {useThemeConfig} from '@docusaurus/theme-common';
+import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
 import NavbarItem, {type Props as NavbarItemConfig} from '@theme/NavbarItem';
 
 function useNavbarItems() {

packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/SecondaryMenu/index.tsx

@@ -6,7 +6,8 @@
  */
 
 import React, {type ComponentProps} from 'react';
-import {useNavbarSecondaryMenu, useThemeConfig} from '@docusaurus/theme-common';
+import {useThemeConfig} from '@docusaurus/theme-common';
+import {useNavbarSecondaryMenu} from '@docusaurus/theme-common/internal';
 import Translate from '@docusaurus/Translate';
 
 function SecondaryMenuBackButton(props: ComponentProps<'button'>) {

packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/Toggle/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import {useNavbarMobileSidebar} from '@docusaurus/theme-common';
+import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
 import IconMenu from '@theme/IconMenu';
 
 export default function MobileSidebarToggle(): JSX.Element {

packages/docusaurus-theme-classic/src/theme/Navbar/MobileSidebar/index.tsx

@@ -9,7 +9,7 @@ import React from 'react';
 import {
   useLockBodyScroll,
   useNavbarMobileSidebar,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import NavbarMobileSidebarLayout from '@theme/Navbar/MobileSidebar/Layout';
 import NavbarMobileSidebarHeader from '@theme/Navbar/MobileSidebar/Header';
 import NavbarMobileSidebarPrimaryMenu from '@theme/Navbar/MobileSidebar/PrimaryMenu';

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocNavbarItem.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import {useActiveDocContext} from '@docusaurus/plugin-content-docs/client';
-import {useLayoutDoc} from '@docusaurus/theme-common';
+import {useLayoutDoc} from '@docusaurus/theme-common/internal';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import type {Props} from '@theme/NavbarItem/DocNavbarItem';
 

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocSidebarNavbarItem.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import {useActiveDocContext} from '@docusaurus/plugin-content-docs/client';
-import {useLayoutDocsSidebar} from '@docusaurus/theme-common';
+import {useLayoutDocsSidebar} from '@docusaurus/theme-common/internal';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import type {Props} from '@theme/NavbarItem/DocSidebarNavbarItem';
 

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx

@@ -13,7 +13,7 @@ import {
 import {
   useDocsPreferredVersion,
   useDocsVersionCandidates,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionNavbarItem.tsx

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import {useDocsVersionCandidates} from '@docusaurus/theme-common';
+import {useDocsVersionCandidates} from '@docusaurus/theme-common/internal';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import type {Props} from '@theme/NavbarItem/DocsVersionNavbarItem';
 import type {GlobalVersion} from '@docusaurus/plugin-content-docs/client';

packages/docusaurus-theme-classic/src/theme/NavbarItem/DropdownNavbarItem.tsx

@@ -8,12 +8,11 @@
 import React, {useState, useRef, useEffect} from 'react';
 import clsx from 'clsx';
 import {
-  isSamePath,
+  isRegexpStringMatch,
   useCollapsible,
   Collapsible,
-  isRegexpStringMatch,
-  useLocalPathname,
 } from '@docusaurus/theme-common';
+import {isSamePath, useLocalPathname} from '@docusaurus/theme-common/internal';
 import NavbarNavLink from '@theme/NavbarItem/NavbarNavLink';
 import NavbarItem, {type LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 import type {

packages/docusaurus-theme-classic/src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import {useAlternatePageUtils} from '@docusaurus/theme-common';
+import {useAlternatePageUtils} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
 import IconLanguage from '@theme/IconLanguage';

packages/docusaurus-theme-classic/src/theme/SiteMetadata/index.tsx

@@ -9,13 +9,12 @@ import React from 'react';
 import Head from '@docusaurus/Head';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import useBaseUrl from '@docusaurus/useBaseUrl';
+import {PageMetadata, useThemeConfig} from '@docusaurus/theme-common';
 import {
-  PageMetadata,
   DEFAULT_SEARCH_TAG,
   useAlternatePageUtils,
-  useThemeConfig,
   keyboardFocusedClassName,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import {useLocation} from '@docusaurus/router';
 import SearchMetadata from '@theme/SearchMetadata';
 

packages/docusaurus-theme-classic/src/theme/SkipToContent/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import Translate from '@docusaurus/Translate';
-import {useSkipToContent} from '@docusaurus/theme-common';
+import {useSkipToContent} from '@docusaurus/theme-common/internal';
 
 import styles from './styles.module.css';
 

packages/docusaurus-theme-classic/src/theme/TOCItems/index.tsx

@@ -6,12 +6,12 @@
  */
 
 import React, {useMemo} from 'react';
+import {useThemeConfig} from '@docusaurus/theme-common';
 import {
-  type TOCHighlightConfig,
-  useThemeConfig,
   useTOCHighlight,
   useFilteredAndTreeifiedTOC,
-} from '@docusaurus/theme-common';
+  type TOCHighlightConfig,
+} from '@docusaurus/theme-common/internal';
 import TOCItemTree from '@theme/TOCItems/Tree';
 import type {Props} from '@theme/TOCItems';
 

packages/docusaurus-theme-classic/src/theme/Tabs/__tests__/index.test.tsx

@@ -10,7 +10,7 @@ import renderer from 'react-test-renderer';
 import {
   TabGroupChoiceProvider,
   ScrollControllerProvider,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import Tabs from '../index';
 import TabItem from '../../TabItem';
 

packages/docusaurus-theme-classic/src/theme/Tabs/index.tsx

@@ -13,11 +13,11 @@ import React, {
 } from 'react';
 import clsx from 'clsx';
 import useIsBrowser from '@docusaurus/useIsBrowser';
+import {duplicates} from '@docusaurus/theme-common';
 import {
   useScrollPositionBlocker,
-  duplicates,
   useTabGroupChoice,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/theme-common/internal';
 import type {Props} from '@theme/Tabs';
 import type {Props as TabItemProps} from '@theme/TabItem';
 

packages/docusaurus-theme-common/.npmignore

@@ -1,3 +1,4 @@
 .tsbuildinfo*
 tsconfig*
 __tests__
+removeThemeInternalReexport.mjs

packages/docusaurus-theme-common/package.json

@@ -10,13 +10,15 @@
   ],
   "exports": {
     ".": "./lib/index.js",
+    "./internal": "./lib/internal.js",
     "./Details": "./lib/components/Details/index.js"
   },
   "scripts": {
     "build": "tsc && node ../../admin/scripts/copyUntypedFiles.js",
     "watch": "run-p -c copy:watch build:watch",
     "build:watch": "tsc --watch",
-    "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
+    "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch",
+    "removeThemeInternalReexport": "node removeThemeInternalReexport.mjs"
   },
   "publishConfig": {
     "access": "public"

packages/docusaurus-theme-common/removeThemeInternalReexport.mjs

@@ -0,0 +1,32 @@
+/**
+ * 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 fs from 'fs-extra';
+
+// See comment in src/internal.ts
+// This script should be run by CI tests to remove:
+// export * from './index'
+
+const filePath = 'lib/internal.js';
+const lineToRemove = "export * from './index';\n";
+
+if (!(await fs.pathExists(filePath))) {
+  throw new Error(`internal entrypoint file not found at ${filePath}`);
+}
+
+const fileContent = await fs.readFile(filePath, 'utf8');
+
+const fileContentUpdated = fileContent.replaceAll(lineToRemove, '');
+
+// Ensure the script correctly removes the re-export
+if (fileContent === fileContentUpdated) {
+  throw new Error(
+    'Unexpected: internal re-export has not been replaced.\nMake sure this script works, and is only run once.',
+  );
+}
+
+await fs.writeFile(filePath, fileContentUpdated);

packages/docusaurus-theme-common/src/index.ts

@@ -5,6 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/*
+ * APIs to document
+ */
+
 export {
   useThemeConfig,
   type ThemeConfig,
@@ -19,71 +23,41 @@ export {
   type FooterLinkItem,
   type ColorModeConfig,
 } from './utils/useThemeConfig';
-export {
-  DocSidebarItemsExpandedStateProvider,
-  useDocSidebarItemsExpandedState,
-} from './contexts/docSidebarItemsExpandedState';
-export {DocsVersionProvider, useDocsVersion} from './contexts/docsVersion';
-export {DocsSidebarProvider, useDocsSidebar} from './contexts/docsSidebar';
-export {DocProvider, useDoc} from './contexts/doc';
-export type {DocContextValue} from './contexts/doc';
 
 export {createStorageSlot, listStorageKeys} from './utils/storageUtils';
 
-export {useAlternatePageUtils} from './utils/useAlternatePageUtils';
+export {useContextualSearchFilters} from './utils/searchUtils';
 
-export {
+export {useCurrentSidebarCategory} from './utils/docsUtils';
-  parseCodeBlockTitle,
-  parseLanguage,
-  parseLines,
-  containsLineNumbers,
-  getPrismCssVariables,
-} from './utils/codeBlockUtils';
-
-export {
-  docVersionSearchTag,
-  DEFAULT_SEARCH_TAG,
-  useContextualSearchFilters,
-} from './utils/searchUtils';
-
-export {
-  isDocsPluginEnabled,
-  useDocById,
-  findSidebarCategory,
-  findFirstCategoryLink,
-  useCurrentSidebarCategory,
-  isActiveSidebarItem,
-  useSidebarBreadcrumbs,
-  useDocsVersionCandidates,
-  useLayoutDoc,
-  useLayoutDocsSidebar,
-  useDocRouteMetadata,
-} from './utils/docsUtils';
-
-export {useTitleFormatter} from './utils/generalUtils';
 
 export {usePluralForm} from './utils/usePluralForm';
 
-export {useLocationChange} from './utils/useLocationChange';
-
 export {useCollapsible, Collapsible} from './components/Collapsible';
 
-export {
-  useDocsPreferredVersion,
-  useDocsPreferredVersionByPluginId,
-  DocsPreferredVersionContextProvider,
-} from './contexts/docsPreferredVersion';
-
-export {duplicates, uniq} from './utils/jsUtils';
-
 export {ThemeClassNames} from './utils/ThemeClassNames';
 
 export {
-  AnnouncementBarProvider,
+  useIsomorphicLayoutEffect,
-  useAnnouncementBar,
+  useDynamicCallback, // TODO rename to useEvent()
-} from './contexts/announcementBar';
+  usePrevious,
+  ReactContextError,
+} from './utils/reactUtils';
 
-export {useLocalPathname} from './utils/useLocalPathname';
+export {PageMetadata, HtmlClassNameProvider} from './utils/metadataUtils';
+
+export {useColorMode, type ColorMode} from './contexts/colorMode';
+
+export {
+  NavbarSecondaryMenuFiller,
+  type NavbarSecondaryMenuComponent,
+} from './contexts/navbarSecondaryMenu/content';
+
+export {useWindowSize} from './hooks/useWindowSize';
+
+/*
+ * APIs kept undocumented, on purpose
+ * Note: we still guarantee retro-compatibility on those
+ */
 
 export {
   translateTagsPageTitle,
@@ -91,75 +65,10 @@ export {
   type TagLetterEntry,
 } from './utils/tagsUtils';
 
-export {useHistoryPopHandler} from './utils/historyUtils';
-
-export {
-  useTOCHighlight,
-  type TOCHighlightConfig,
-} from './hooks/useTOCHighlight';
-
-export {
-  useFilteredAndTreeifiedTOC,
-  useTreeifiedTOC,
-  type TOCTreeNode,
-} from './utils/tocUtils';
-
 export {isMultiColumnFooterLinks} from './utils/footerUtils';
 
-export {
-  ScrollControllerProvider,
-  useScrollController,
-  useScrollPosition,
-  useScrollPositionBlocker,
-  useSmoothScrollTo,
-} from './utils/scrollUtils';
-
-export {
-  useIsomorphicLayoutEffect,
-  useDynamicCallback,
-  usePrevious,
-  ReactContextError,
-} from './utils/reactUtils';
-
 export {isRegexpStringMatch} from './utils/regexpUtils';
 
-export {useHomePageRoute, isSamePath} from './utils/routesUtils';
+export {duplicates, uniq} from './utils/jsUtils';
 
-export {
-  PageMetadata,
-  HtmlClassNameProvider,
-  PluginHtmlClassNameProvider,
-} from './utils/metadataUtils';
-
-export {
-  useColorMode,
-  ColorModeProvider,
-  type ColorMode,
-} from './contexts/colorMode';
-
-export {splitNavbarItems, NavbarProvider} from './utils/navbarUtils';
-
-export {
-  useTabGroupChoice,
-  TabGroupChoiceProvider,
-} from './contexts/tabGroupChoice';
-
-export {useNavbarMobileSidebar} from './contexts/navbarMobileSidebar';
-export {
-  NavbarSecondaryMenuFiller,
-  type NavbarSecondaryMenuComponent,
-} from './contexts/navbarSecondaryMenu/content';
-export {useNavbarSecondaryMenu} from './contexts/navbarSecondaryMenu/display';
-
-export {useBackToTopButton} from './hooks/useBackToTopButton';
-export {useHideableNavbar} from './hooks/useHideableNavbar';
-export {
-  useKeyboardNavigation,
-  keyboardFocusedClassName,
-} from './hooks/useKeyboardNavigation';
 export {usePrismTheme} from './hooks/usePrismTheme';
-export {useLockBodyScroll} from './hooks/useLockBodyScroll';
-export {useWindowSize} from './hooks/useWindowSize';
-export {useSearchPage} from './hooks/useSearchPage';
-export {useCodeWordWrap} from './hooks/useCodeWordWrap';
-export {useSkipToContent} from './hooks/useSkipToContent';

packages/docusaurus-theme-common/src/internal.ts

@@ -0,0 +1,117 @@
+/**
+ * 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.
+ */
+
+// This re-export permits to handle some level of retro-compatibility. Users
+// might swizzle unsafe components and expose these internal imports. When we
+// move an API from internal to public, former internal imports should keep
+// working, so that the change doesn't become breaking.
+//
+// Important: this line is removed from build output with the
+// "removeThemeInternalReexport" script for CI checks. This ensures that none of
+// our internal code relies on this re-export and that we don't forget to
+// migrate theme internal imports to public imports.
+//
+// eslint-disable-next-line no-restricted-syntax
+export * from './index';
+
+export {
+  DocSidebarItemsExpandedStateProvider,
+  useDocSidebarItemsExpandedState,
+} from './contexts/docSidebarItemsExpandedState';
+export {DocsVersionProvider, useDocsVersion} from './contexts/docsVersion';
+export {DocsSidebarProvider, useDocsSidebar} from './contexts/docsSidebar';
+export {DocProvider, useDoc, type DocContextValue} from './contexts/doc';
+
+export {
+  useDocsPreferredVersion,
+  useDocsPreferredVersionByPluginId,
+  DocsPreferredVersionContextProvider,
+} from './contexts/docsPreferredVersion';
+
+export {
+  AnnouncementBarProvider,
+  useAnnouncementBar,
+} from './contexts/announcementBar';
+
+export {
+  useTabGroupChoice,
+  TabGroupChoiceProvider,
+} from './contexts/tabGroupChoice';
+
+export {useNavbarMobileSidebar} from './contexts/navbarMobileSidebar';
+export {useNavbarSecondaryMenu} from './contexts/navbarSecondaryMenu/display';
+
+export {ColorModeProvider} from './contexts/colorMode';
+
+export {useAlternatePageUtils} from './utils/useAlternatePageUtils';
+
+export {
+  parseCodeBlockTitle,
+  parseLanguage,
+  parseLines,
+  containsLineNumbers,
+} from './utils/codeBlockUtils';
+
+export {docVersionSearchTag, DEFAULT_SEARCH_TAG} from './utils/searchUtils';
+
+export {
+  isDocsPluginEnabled,
+  useDocById,
+  findSidebarCategory,
+  findFirstCategoryLink,
+  isActiveSidebarItem,
+  useSidebarBreadcrumbs,
+  useDocsVersionCandidates,
+  useLayoutDoc,
+  useLayoutDocsSidebar,
+  useDocRouteMetadata,
+} from './utils/docsUtils';
+
+export {useTitleFormatter} from './utils/generalUtils';
+
+export {useLocationChange} from './utils/useLocationChange';
+
+export {useLocalPathname} from './utils/useLocalPathname';
+
+export {useHistoryPopHandler} from './utils/historyUtils';
+
+export {
+  useFilteredAndTreeifiedTOC,
+  useTreeifiedTOC,
+  type TOCTreeNode,
+} from './utils/tocUtils';
+
+export {
+  ScrollControllerProvider,
+  useScrollController,
+  useScrollPosition,
+  useScrollPositionBlocker,
+  useSmoothScrollTo,
+} from './utils/scrollUtils';
+
+export {useHomePageRoute, isSamePath} from './utils/routesUtils';
+
+export {PluginHtmlClassNameProvider} from './utils/metadataUtils';
+
+export {splitNavbarItems, NavbarProvider} from './utils/navbarUtils';
+
+export {
+  useTOCHighlight,
+  type TOCHighlightConfig,
+} from './hooks/useTOCHighlight';
+
+export {useHideableNavbar} from './hooks/useHideableNavbar';
+export {
+  useKeyboardNavigation,
+  keyboardFocusedClassName,
+} from './hooks/useKeyboardNavigation';
+export {useLockBodyScroll} from './hooks/useLockBodyScroll';
+export {useSearchPage} from './hooks/useSearchPage';
+export {useCodeWordWrap} from './hooks/useCodeWordWrap';
+export {useSkipToContent} from './hooks/useSkipToContent';
+export {getPrismCssVariables} from './utils/codeBlockUtils';
+export {useBackToTopButton} from './hooks/useBackToTopButton';

packages/docusaurus-theme-search-algolia/src/theme/SearchBar/index.tsx

@@ -12,7 +12,8 @@ import {useHistory} from '@docusaurus/router';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
 import Link from '@docusaurus/Link';
 import Head from '@docusaurus/Head';
-import {isRegexpStringMatch, useSearchPage} from '@docusaurus/theme-common';
+import {isRegexpStringMatch} from '@docusaurus/theme-common';
+import {useSearchPage} from '@docusaurus/theme-common/internal';
 import {DocSearchButton, useDocSearchKeyboardEvents} from '@docsearch/react';
 import {useAlgoliaContextualFacetFilters} from '@docusaurus/theme-search-algolia/client';
 import Translate, {translate} from '@docusaurus/Translate';

packages/docusaurus-theme-search-algolia/src/theme/SearchPage/index.tsx

@@ -18,12 +18,14 @@ import Link from '@docusaurus/Link';
 import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
 import {
   HtmlClassNameProvider,
-  useTitleFormatter,
   usePluralForm,
   isRegexpStringMatch,
   useDynamicCallback,
-  useSearchPage,
 } from '@docusaurus/theme-common';
+import {
+  useTitleFormatter,
+  useSearchPage,
+} from '@docusaurus/theme-common/internal';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useAllDocsData} from '@docusaurus/plugin-content-docs/client';
 import Translate, {translate} from '@docusaurus/Translate';

website/src/components/Versions.tsx

@@ -12,7 +12,7 @@ import React, {
   useRef,
   type ReactNode,
 } from 'react';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+import {useDocsPreferredVersion} from '@docusaurus/theme-common/internal';
 import {useVersions} from '@docusaurus/plugin-content-docs/client';
 import Translate from '@docusaurus/Translate';
 import CodeBlock from '@theme/CodeBlock';

website/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import {useLayoutDoc} from '@docusaurus/theme-common';
+import {useLayoutDoc} from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
 import DocCategoryGeneratedIndexPage from '@theme-original/DocCategoryGeneratedIndexPage';