fix(theme): make `useHistorySelector()` hydration-safe + use it read search/hash in theme (#11263)

argos/tests/screenshot.spec.ts

@@ -134,11 +134,6 @@ function throwOnConsole(page: Page) {
     //  it's already happening in main branch
     'Failed to load resource: the server responded with a status of 404 (Not Found)',
 
-    // TODO legit hydration bugs to fix on embeds of /docs/styling-layout
-    //  useLocation() returns window.search/hash immediately :s
-    '/docs/configuration?docusaurus-theme=light',
-    '/docs/configuration?docusaurus-theme=dark',
-
     // Warning because react-live not supporting React automatic JSX runtime
     // See https://github.com/FormidableLabs/react-live/issues/405
     'Your app (or one of its dependencies) is using an outdated JSX transform. Update to the modern JSX transform for faster performance',

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

@@ -13,7 +13,7 @@ import {
   useDocsPreferredVersion,
 } from '@docusaurus/plugin-content-docs/client';
 import {translate} from '@docusaurus/Translate';
-import {useLocation} from '@docusaurus/router';
+import {useHistorySelector} from '@docusaurus/theme-common';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
 import type {
@@ -119,7 +119,8 @@ export default function DocsVersionDropdownNavbarItem({
   versions: configs,
   ...props
 }: Props): ReactNode {
-  const {search, hash} = useLocation();
+  const search = useHistorySelector((history) => history.location.search);
+  const hash = useHistorySelector((history) => history.location.hash);
   const activeDocContext = useActiveDocContext(docsPluginId);
   const {savePreferredVersionName} = useDocsPreferredVersion(docsPluginId);
   const versionItems = useVersionItems({docsPluginId, configs});

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

@@ -9,7 +9,7 @@ import React, {type ReactNode} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useAlternatePageUtils} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
-import {useLocation} from '@docusaurus/router';
+import {useHistorySelector} from '@docusaurus/theme-common';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
 import IconLanguage from '@theme/Icon/Language';
 import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
@@ -28,7 +28,8 @@ export default function LocaleDropdownNavbarItem({
     i18n: {currentLocale, locales, localeConfigs},
   } = useDocusaurusContext();
   const alternatePageUtils = useAlternatePageUtils();
-  const {search, hash} = useLocation();
+  const search = useHistorySelector((history) => history.location.search);
+  const hash = useHistorySelector((history) => history.location.hash);
 
   const localeItems = locales.map((locale): LinkLikeNavbarItemProps => {
     const baseTo = `pathname://${alternatePageUtils.createUrl({

packages/docusaurus-theme-common/src/utils/historyUtils.ts

@@ -57,7 +57,18 @@ export function useHistorySelector<Value>(
   return useSyncExternalStore(
     history.listen,
     () => selector(history),
-    () => selector(history),
+    () =>
+      selector({
+        ...history,
+        location: {
+          ...history.location,
+          // On the server/hydration, these attributes should always be empty
+          // Forcing empty state makes this hook safe from hydration errors
+          search: '',
+          hash: '',
+          state: undefined,
+        },
+      }),
   );
 }