refactor(docs): theme-common shouldn't depend on docs content (#10316)

.github/workflows/tests-e2e.yml

@@ -102,19 +102,11 @@ jobs:
         working-directory: ../test-website
         env:
           YARN_ENABLE_IMMUTABLE_INSTALLS: false # Yarn berry should create the lockfile, despite CI env
-      - name: Install missing dependencies
-        if: matrix.variant == '-st' && matrix.nodeLinker == 'pnp'
-        run: |
-          # These dependencies are referenced in the init project, not by our packages
-          yarn add @docusaurus/theme-classic @docusaurus/types @types/node
-          yarn config set packageExtensions --json '{ "unified@^9.2.2": { "dependencies": { "@types/unist": "^2.0.6" } } }'
-        working-directory: ../test-website
       - name: Start test-website project
         run: yarn start --no-open
         working-directory: ../test-website
         env:
           E2E_TEST: true
-
       - name: TypeCheck website
         # TODO: there're some lingering issues with PnP + tsc. Enable tsc in PnP later.
         if: matrix.variant == '-st' && matrix.nodeLinker != 'pnp'

packages/docusaurus-plugin-content-blog/package.json

@@ -52,7 +52,8 @@
   },
   "peerDependencies": {
     "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "react-dom": "^18.0.0",
+    "@docusaurus/plugin-content-docs": "*"
   },
   "engines": {
     "node": ">=18.0"

packages/docusaurus-plugin-content-docs/package.json

@@ -39,6 +39,7 @@
     "@docusaurus/logger": "3.4.0",
     "@docusaurus/mdx-loader": "3.4.0",
     "@docusaurus/module-type-aliases": "3.4.0",
+    "@docusaurus/theme-common": "3.4.0",
     "@docusaurus/types": "3.4.0",
     "@docusaurus/utils": "3.4.0",
     "@docusaurus/utils-common": "3.4.0",

packages/docusaurus-plugin-content-docs/src/client/__tests__/docsClientUtils.test.ts

@@ -18,7 +18,7 @@ import type {
   GlobalVersion,
   ActivePlugin,
   GlobalDoc,
-} from '@docusaurus/plugin-content-docs/client';
+} from '../index';
 
 describe('docsClientUtils', () => {
   it('getActivePlugin', () => {

packages/docusaurus-theme-common/src/utils/__tests__/docsUtils.test.tsx → packages/docusaurus-plugin-content-docs/src/client/__tests__/docsUtils.test.tsx

@@ -18,8 +18,8 @@ import {
   useSidebarBreadcrumbs,
   isVisibleSidebarItem,
 } from '../docsUtils';
-import {DocsSidebarProvider} from '../../contexts/docsSidebar';
-import {DocsVersionProvider} from '../../contexts/docsVersion';
+import {DocsSidebarProvider} from '../docsSidebar';
+import {DocsVersionProvider} from '../docsVersion';
 import type {
   PropSidebar,
   PropSidebarItem,

packages/docusaurus-theme-common/src/contexts/doc.tsx → packages/docusaurus-plugin-content-docs/src/client/doc.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {useMemo, type ReactNode, useContext} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
 import type {PropDocContent} from '@docusaurus/plugin-content-docs';
 
 /**

packages/docusaurus-theme-common/src/contexts/docSidebarItemsExpandedState.tsx → packages/docusaurus-plugin-content-docs/src/client/docSidebarItemsExpandedState.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {type ReactNode, useMemo, useState, useContext} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
 
 type ContextValue = {
   /**

packages/docusaurus-theme-common/src/contexts/docsPreferredVersion.tsx → packages/docusaurus-plugin-content-docs/src/client/docsPreferredVersion.tsx

@@ -20,13 +20,13 @@ import {
   type GlobalVersion,
 } from '@docusaurus/plugin-content-docs/client';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/constants';
+import {useThemeConfig, type ThemeConfig} from '@docusaurus/theme-common';
 import {
-  useThemeConfig,
-  type DocsVersionPersistence,
-} from '../utils/useThemeConfig';
-import {isDocsPluginEnabled} from '../utils/docsUtils';
-import {ReactContextError} from '../utils/reactUtils';
-import {createStorageSlot} from '../utils/storageUtils';
+  ReactContextError,
+  createStorageSlot,
+} from '@docusaurus/theme-common/internal';
+
+type DocsVersionPersistence = ThemeConfig['docs']['versionPersistence'];
 
 const storageKey = (pluginId: string) => `docs-preferred-version-${pluginId}`;
 
@@ -177,14 +177,11 @@ export function DocsPreferredVersionContextProvider({
 }: {
   children: ReactNode;
 }): JSX.Element {
-  if (isDocsPluginEnabled) {
-    return (
-      <DocsPreferredVersionContextProviderUnsafe>
-        {children}
-      </DocsPreferredVersionContextProviderUnsafe>
-    );
-  }
-  return <>{children}</>;
+  return (
+    <DocsPreferredVersionContextProviderUnsafe>
+      {children}
+    </DocsPreferredVersionContextProviderUnsafe>
+  );
 }
 
 function useDocsPreferredVersionContext(): ContextValue {

packages/docusaurus-theme-common/src/utils/__tests__/searchUtils.test.ts → packages/docusaurus-plugin-content-docs/src/client/docsSearch.test.ts

@@ -5,10 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {docVersionSearchTag} from '../searchUtils';
+import {getDocsVersionSearchTag} from './docsSearch';
 
-describe('docVersionSearchTag', () => {
+describe('getDocsVersionSearchTag', () => {
   it('works', () => {
-    expect(docVersionSearchTag('foo', 'bar')).toBe('docs-foo-bar');
+    expect(getDocsVersionSearchTag('foo', 'bar')).toBe('docs-foo-bar');
   });
 });

packages/docusaurus-plugin-content-docs/src/client/docsSearch.ts

@@ -0,0 +1,57 @@
+/**
+ * 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 {
+  useAllDocsData,
+  useActivePluginAndVersion,
+} from '@docusaurus/plugin-content-docs/client';
+import {useDocsPreferredVersionByPluginId} from './docsPreferredVersion';
+
+/** The search tag to append as each doc's metadata. */
+export function getDocsVersionSearchTag(
+  pluginId: string,
+  versionName: string,
+): string {
+  return `docs-${pluginId}-${versionName}`;
+}
+
+/**
+ * Gets the relevant docs tags to search.
+ * This is the logic that powers the contextual search feature.
+ *
+ * If user is browsing Android 1.4 docs, he'll get presented with:
+ * - Android '1.4' docs
+ * - iOS 'preferred | latest' docs
+ *
+ * The result is generic and not coupled to Algolia/DocSearch on purpose.
+ */
+export function useDocsContextualSearchTags(): string[] {
+  const allDocsData = useAllDocsData();
+  const activePluginAndVersion = useActivePluginAndVersion();
+  const docsPreferredVersionByPluginId = useDocsPreferredVersionByPluginId();
+
+  // This can't use more specialized hooks because we are mapping over all
+  // plugin instances.
+  function getDocPluginTags(pluginId: string) {
+    const activeVersion =
+      activePluginAndVersion?.activePlugin.pluginId === pluginId
+        ? activePluginAndVersion.activeVersion
+        : undefined;
+
+    const preferredVersion = docsPreferredVersionByPluginId[pluginId];
+
+    const latestVersion = allDocsData[pluginId]!.versions.find(
+      (v) => v.isLast,
+    )!;
+
+    const version = activeVersion ?? preferredVersion ?? latestVersion;
+
+    return getDocsVersionSearchTag(pluginId, version.name);
+  }
+
+  return [...Object.keys(allDocsData).map(getDocPluginTags)];
+}

packages/docusaurus-theme-common/src/contexts/docsSidebar.tsx → packages/docusaurus-plugin-content-docs/src/client/docsSidebar.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {useMemo, useContext, type ReactNode} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
 import type {PropSidebar} from '@docusaurus/plugin-content-docs';
 
 // Using a Symbol because null is a valid context value (a doc with no sidebar)

packages/docusaurus-theme-common/src/utils/docsUtils.tsx → packages/docusaurus-plugin-content-docs/src/client/docsUtils.tsx

@@ -9,20 +9,20 @@ import {useMemo} from 'react';
 import {matchPath, useLocation} from '@docusaurus/router';
 import renderRoutes from '@docusaurus/renderRoutes';
 import {
-  useAllDocsData,
   useActivePlugin,
   useActiveDocContext,
   useLatestVersion,
   type GlobalVersion,
   type GlobalSidebar,
   type GlobalDoc,
 } from '@docusaurus/plugin-content-docs/client';
+import {isSamePath} from '@docusaurus/theme-common/internal';
+import {uniq} from '@docusaurus/theme-common';
 import type {Props as DocRootProps} from '@theme/DocRoot';
-import {useDocsPreferredVersion} from '../contexts/docsPreferredVersion';
-import {useDocsVersion} from '../contexts/docsVersion';
-import {useDocsSidebar} from '../contexts/docsSidebar';
-import {uniq} from './jsUtils';
-import {isSamePath} from './routesUtils';
+import {useDocsPreferredVersion} from './docsPreferredVersion';
+import {useDocsVersion} from './docsVersion';
+import {useDocsSidebar} from './docsSidebar';
+
 import type {
   PropSidebar,
   PropSidebarItem,
@@ -31,9 +31,6 @@ import type {
   PropSidebarBreadcrumbsItem,
 } from '@docusaurus/plugin-content-docs';
 
-// TODO not ideal, see also "useDocs"
-export const isDocsPluginEnabled: boolean = !!useAllDocsData;
-
 /**
  * A null-safe way to access a doc's data by ID in the active version.
  */

packages/docusaurus-theme-common/src/contexts/docsVersion.tsx → packages/docusaurus-plugin-content-docs/src/client/docsVersion.tsx

@@ -6,7 +6,7 @@
  */
 
 import React, {type ReactNode, useContext} from 'react';
-import {ReactContextError} from '../utils/reactUtils';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
 import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs';
 
 const Context = React.createContext<PropVersionMetadata | null>(null);

packages/docusaurus-plugin-content-docs/src/client/index.ts

@@ -20,6 +20,45 @@ import {
 } from './docsClientUtils';
 import type {UseDataOptions} from '@docusaurus/types';
 
+export {
+  useDocById,
+  findSidebarCategory,
+  findFirstSidebarItemLink,
+  isActiveSidebarItem,
+  isVisibleSidebarItem,
+  useVisibleSidebarItems,
+  useSidebarBreadcrumbs,
+  useDocsVersionCandidates,
+  useLayoutDoc,
+  useLayoutDocsSidebar,
+  useDocRootMetadata,
+  useCurrentSidebarCategory,
+  filterDocCardListItems,
+} from './docsUtils';
+
+export {useDocsPreferredVersion} from './docsPreferredVersion';
+
+export {
+  DocSidebarItemsExpandedStateProvider,
+  useDocSidebarItemsExpandedState,
+} from './docSidebarItemsExpandedState';
+
+export {DocsVersionProvider, useDocsVersion} from './docsVersion';
+
+export {DocsSidebarProvider, useDocsSidebar} from './docsSidebar';
+
+export {DocProvider, useDoc, type DocContextValue} from './doc';
+
+export {
+  useDocsPreferredVersionByPluginId,
+  DocsPreferredVersionContextProvider,
+} from './docsPreferredVersion';
+
+export {
+  useDocsContextualSearchTags,
+  getDocsVersionSearchTag,
+} from './docsSearch';
+
 export type ActivePlugin = {
   pluginId: string;
   pluginData: GlobalPluginData;

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

@@ -8,10 +8,8 @@
 import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {
-  useSidebarBreadcrumbs,
-  useHomePageRoute,
-} from '@docusaurus/theme-common/internal';
+import {useSidebarBreadcrumbs} from '@docusaurus/plugin-content-docs/client';
+import {useHomePageRoute} from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
 import {translate} from '@docusaurus/Translate';
 import HomeBreadcrumbItem from '@theme/DocBreadcrumbs/Items/Home';

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

@@ -9,9 +9,9 @@ import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import {
-  findFirstSidebarItemLink,
   useDocById,
-} from '@docusaurus/theme-common/internal';
+  findFirstSidebarItemLink,
+} from '@docusaurus/plugin-content-docs/client';
 import {usePluralForm} from '@docusaurus/theme-common';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import {translate} from '@docusaurus/Translate';

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

@@ -10,7 +10,7 @@ import clsx from 'clsx';
 import {
   useCurrentSidebarCategory,
   filterDocCardListItems,
-} from '@docusaurus/theme-common';
+} from '@docusaurus/plugin-content-docs/client';
 import DocCard from '@theme/DocCard';
 import type {Props} from '@theme/DocCardList';
 

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

@@ -6,10 +6,8 @@
  */
 
 import React from 'react';
-import {
-  PageMetadata,
-  useCurrentSidebarCategory,
-} from '@docusaurus/theme-common';
+import {PageMetadata} from '@docusaurus/theme-common';
+import {useCurrentSidebarCategory} from '@docusaurus/plugin-content-docs/client';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 import DocCardList from '@theme/DocCardList';
 import DocPaginator from '@theme/DocPaginator';

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

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 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

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 import TagsListInline from '@theme/TagsListInline';
 
 import EditMetaRow from '@theme/EditMetaRow';

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

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {useWindowSize} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 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

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import {PageMetadata} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 
 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/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 import DocPaginator from '@theme/DocPaginator';
 
 /**

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

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 
 import TOC from '@theme/TOC';
 

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

@@ -8,7 +8,7 @@
 import React from 'react';
 import clsx from 'clsx';
 import {ThemeClassNames} from '@docusaurus/theme-common';
-import {useDoc} from '@docusaurus/theme-common/internal';
+import {useDoc} from '@docusaurus/plugin-content-docs/client';
 
 import TOCCollapsible from '@theme/TOCCollapsible';