@docusaurus/theme-classic 0.0.0-5406 → 0.0.0-5408

package/lib/theme/Tabs/index.js

@@ -4,20 +4,66 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, {useState, cloneElement, isValidElement} from 'react';
+import React, {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useState,
+} from 'react';
 import clsx from 'clsx';
-import useIsBrowser from '@docusaurus/useIsBrowser';
-import {duplicates} from '@docusaurus/theme-common';
+import {useHistory, useLocation} from '@docusaurus/router';
+import {duplicates, useEvent} from '@docusaurus/theme-common';
 import {
   useScrollPositionBlocker,
   useTabGroupChoice,
 } from '@docusaurus/theme-common/internal';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import styles from './styles.module.css';
 // A very rough duck type, but good enough to guard against mistakes while
 // allowing customization
 function isTabItem(comp) {
   return 'value' in comp.props;
 }
+function getSearchKey({queryString = false, groupId}) {
+  if (typeof queryString === 'string') {
+    return queryString;
+  }
+  if (queryString === false) {
+    return undefined;
+  }
+  if (queryString === true && !groupId) {
+    throw new Error(
+      `Docusaurus error: The <Tabs> component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".`,
+    );
+  }
+  return groupId;
+}
+function useTabQueryString({queryString = false, groupId}) {
+  // TODO not re-render optimized
+  // See https://thisweekinreact.com/articles/useSyncExternalStore-the-underrated-react-api
+  const location = useLocation();
+  const history = useHistory();
+  const searchKey = getSearchKey({queryString, groupId});
+  const get = useCallback(() => {
+    if (!searchKey) {
+      return undefined;
+    }
+    return new URLSearchParams(location.search).get(searchKey);
+  }, [searchKey, location.search]);
+  const set = useCallback(
+    (newTabValue) => {
+      if (!searchKey) {
+        return; // no-op
+      }
+      const searchParams = new URLSearchParams(location.search);
+      searchParams.set(searchKey, newTabValue);
+      history.replace({...location, search: searchParams.toString()});
+    },
+    [searchKey, history, location],
+  );
+  return {get, set};
+}
 function TabsComponent(props) {
   const {
     lazy,
@@ -26,6 +72,7 @@ function TabsComponent(props) {
     values: valuesProp,
     groupId,
     className,
+    queryString = false,
   } = props;
   const children = React.Children.map(props.children, (child) => {
     if (isValidElement(child) && isTabItem(child)) {
@@ -40,6 +87,7 @@ function TabsComponent(props) {
       }>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`,
     );
   });
+  const tabQueryString = useTabQueryString({queryString, groupId});
   const values =
     valuesProp ??
     // Only pick keys that we recognize. MDX would inject some keys by default
@@ -56,37 +104,57 @@ function TabsComponent(props) {
         .join(', ')}" found in <Tabs>. Every value needs to be unique.`,
     );
   }
-  // When defaultValueProp is null, don't show a default tab
-  const defaultValue =
-    defaultValueProp === null
-      ? defaultValueProp
-      : defaultValueProp ??
-        children.find((child) => child.props.default)?.props.value ??
-        children[0].props.value;
-  if (defaultValue !== null && !values.some((a) => a.value === defaultValue)) {
+  // Warn user about passing incorrect defaultValue as prop.
+  if (
+    defaultValueProp !== null &&
+    defaultValueProp !== undefined &&
+    !values.some((a) => a.value === defaultValueProp)
+  ) {
     throw new Error(
-      `Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${values
+      `Docusaurus error: The <Tabs> has a defaultValue "${defaultValueProp}" but none of its children has the corresponding value. Available values are: ${values
         .map((a) => a.value)
         .join(
           ', ',
         )}. If you intend to show no default tab, use defaultValue={null} instead.`,
     );
   }
-  const {tabGroupChoices, setTabGroupChoices} = useTabGroupChoice();
+  const {
+    ready: tabGroupChoicesReady,
+    tabGroupChoices,
+    setTabGroupChoices,
+  } = useTabGroupChoice();
+  const defaultValue =
+    defaultValueProp !== undefined
+      ? defaultValueProp
+      : children.find((child) => child.props.default)?.props.value ??
+        children[0].props.value;
   const [selectedValue, setSelectedValue] = useState(defaultValue);
   const tabRefs = [];
   const {blockElementScrollPositionUntilNextRender} =
     useScrollPositionBlocker();
-  if (groupId != null) {
-    const relevantTabGroupChoice = tabGroupChoices[groupId];
-    if (
-      relevantTabGroupChoice != null &&
-      relevantTabGroupChoice !== selectedValue &&
-      values.some((value) => value.value === relevantTabGroupChoice)
-    ) {
-      setSelectedValue(relevantTabGroupChoice);
+  // Lazily restore the appropriate tab selected value
+  // We can't read queryString/localStorage on first render
+  // It would trigger a React SSR/client hydration mismatch
+  const restoreTabSelectedValue = useEvent(() => {
+    // wait for localStorage values to be set (initially empty object :s)
+    if (tabGroupChoicesReady) {
+      // querystring value > localStorage value
+      const valueToRestore =
+        tabQueryString.get() ?? (groupId && tabGroupChoices[groupId]);
+      const isValid =
+        valueToRestore &&
+        values.some((value) => value.value === valueToRestore);
+      if (isValid) {
+        setSelectedValue(valueToRestore);
+      }
     }
-  }
+  });
+  useEffect(() => {
+    // wait for localStorage values to be set (initially empty object :s)
+    if (tabGroupChoicesReady) {
+      restoreTabSelectedValue();
+    }
+  }, [tabGroupChoicesReady, restoreTabSelectedValue]);
   const handleTabChange = (event) => {
     const newTab = event.currentTarget;
     const newTabIndex = tabRefs.indexOf(newTab);
@@ -94,6 +162,7 @@ function TabsComponent(props) {
     if (newTabValue !== selectedValue) {
       blockElementScrollPositionUntilNextRender(newTab);
       setSelectedValue(newTabValue);
+      tabQueryString.set(newTabValue);
       if (groupId != null) {
         setTabGroupChoices(groupId, String(newTabValue));
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "0.0.0-5406",
+  "version": "0.0.0-5408",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,18 +20,18 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "0.0.0-5406",
-    "@docusaurus/mdx-loader": "0.0.0-5406",
-    "@docusaurus/module-type-aliases": "0.0.0-5406",
-    "@docusaurus/plugin-content-blog": "0.0.0-5406",
-    "@docusaurus/plugin-content-docs": "0.0.0-5406",
-    "@docusaurus/plugin-content-pages": "0.0.0-5406",
-    "@docusaurus/theme-common": "0.0.0-5406",
-    "@docusaurus/theme-translations": "0.0.0-5406",
-    "@docusaurus/types": "0.0.0-5406",
-    "@docusaurus/utils": "0.0.0-5406",
-    "@docusaurus/utils-common": "0.0.0-5406",
-    "@docusaurus/utils-validation": "0.0.0-5406",
+    "@docusaurus/core": "0.0.0-5408",
+    "@docusaurus/mdx-loader": "0.0.0-5408",
+    "@docusaurus/module-type-aliases": "0.0.0-5408",
+    "@docusaurus/plugin-content-blog": "0.0.0-5408",
+    "@docusaurus/plugin-content-docs": "0.0.0-5408",
+    "@docusaurus/plugin-content-pages": "0.0.0-5408",
+    "@docusaurus/theme-common": "0.0.0-5408",
+    "@docusaurus/theme-translations": "0.0.0-5408",
+    "@docusaurus/types": "0.0.0-5408",
+    "@docusaurus/utils": "0.0.0-5408",
+    "@docusaurus/utils-common": "0.0.0-5408",
+    "@docusaurus/utils-validation": "0.0.0-5408",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.2.1",
     "copy-text-to-clipboard": "^3.0.1",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "5b76959dddeb67005b131390645836e88ac84637"
+  "gitHead": "6d1f31ee146538494968633a12e92c47cd3de973"
 }

package/src/theme/Tabs/index.tsx

@@ -6,21 +6,23 @@
  */
 
 import React, {
-  useState,
   cloneElement,
   isValidElement,
+  useCallback,
+  useEffect,
+  useState,
   type ReactElement,
 } from 'react';
 import clsx from 'clsx';
-import useIsBrowser from '@docusaurus/useIsBrowser';
-import {duplicates} from '@docusaurus/theme-common';
+import {useHistory, useLocation} from '@docusaurus/router';
+import {duplicates, useEvent} from '@docusaurus/theme-common';
 import {
   useScrollPositionBlocker,
   useTabGroupChoice,
 } from '@docusaurus/theme-common/internal';
-import type {Props} from '@theme/Tabs';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import type {Props as TabItemProps} from '@theme/TabItem';
-
+import type {Props} from '@theme/Tabs';
 import styles from './styles.module.css';
 
 // A very rough duck type, but good enough to guard against mistakes while
@@ -31,6 +33,57 @@ function isTabItem(
   return 'value' in comp.props;
 }
 
+function getSearchKey({
+  queryString = false,
+  groupId,
+}: Pick<Props, 'queryString' | 'groupId'>) {
+  if (typeof queryString === 'string') {
+    return queryString;
+  }
+  if (queryString === false) {
+    return undefined;
+  }
+  if (queryString === true && !groupId) {
+    throw new Error(
+      `Docusaurus error: The <Tabs> component groupId prop is required if queryString=true, because this value is used as the search param name. You can also provide an explicit value such as queryString="my-search-param".`,
+    );
+  }
+  return groupId;
+}
+
+function useTabQueryString({
+  queryString = false,
+  groupId,
+}: Pick<Props, 'queryString' | 'groupId'>) {
+  // TODO not re-render optimized
+  // See https://thisweekinreact.com/articles/useSyncExternalStore-the-underrated-react-api
+  const location = useLocation();
+  const history = useHistory();
+
+  const searchKey = getSearchKey({queryString, groupId});
+
+  const get = useCallback(() => {
+    if (!searchKey) {
+      return undefined;
+    }
+    return new URLSearchParams(location.search).get(searchKey);
+  }, [searchKey, location.search]);
+
+  const set = useCallback(
+    (newTabValue: string) => {
+      if (!searchKey) {
+        return; // no-op
+      }
+      const searchParams = new URLSearchParams(location.search);
+      searchParams.set(searchKey, newTabValue);
+      history.replace({...location, search: searchParams.toString()});
+    },
+    [searchKey, history, location],
+  );
+
+  return {get, set};
+}
+
 function TabsComponent(props: Props): JSX.Element {
   const {
     lazy,
@@ -39,6 +92,7 @@ function TabsComponent(props: Props): JSX.Element {
     values: valuesProp,
     groupId,
     className,
+    queryString = false,
   } = props;
   const children = React.Children.map(props.children, (child) => {
     if (isValidElement(child) && isTabItem(child)) {
@@ -53,6 +107,7 @@ function TabsComponent(props: Props): JSX.Element {
       }>: all children of the <Tabs> component should be <TabItem>, and every <TabItem> should have a unique "value" prop.`,
     );
   });
+  const tabQueryString = useTabQueryString({queryString, groupId});
   const values =
     valuesProp ??
     // Only pick keys that we recognize. MDX would inject some keys by default
@@ -69,16 +124,15 @@ function TabsComponent(props: Props): JSX.Element {
         .join(', ')}" found in <Tabs>. Every value needs to be unique.`,
     );
   }
-  // When defaultValueProp is null, don't show a default tab
-  const defaultValue =
-    defaultValueProp === null
-      ? defaultValueProp
-      : defaultValueProp ??
-        children.find((child) => child.props.default)?.props.value ??
-        children[0]!.props.value;
-  if (defaultValue !== null && !values.some((a) => a.value === defaultValue)) {
+
+  // Warn user about passing incorrect defaultValue as prop.
+  if (
+    defaultValueProp !== null &&
+    defaultValueProp !== undefined &&
+    !values.some((a) => a.value === defaultValueProp)
+  ) {
     throw new Error(
-      `Docusaurus error: The <Tabs> has a defaultValue "${defaultValue}" but none of its children has the corresponding value. Available values are: ${values
+      `Docusaurus error: The <Tabs> has a defaultValue "${defaultValueProp}" but none of its children has the corresponding value. Available values are: ${values
         .map((a) => a.value)
         .join(
           ', ',
@@ -86,22 +140,45 @@ function TabsComponent(props: Props): JSX.Element {
     );
   }
 
-  const {tabGroupChoices, setTabGroupChoices} = useTabGroupChoice();
+  const {
+    ready: tabGroupChoicesReady,
+    tabGroupChoices,
+    setTabGroupChoices,
+  } = useTabGroupChoice();
+  const defaultValue =
+    defaultValueProp !== undefined
+      ? defaultValueProp
+      : children.find((child) => child.props.default)?.props.value ??
+        children[0]!.props.value;
+
   const [selectedValue, setSelectedValue] = useState(defaultValue);
   const tabRefs: (HTMLLIElement | null)[] = [];
   const {blockElementScrollPositionUntilNextRender} =
     useScrollPositionBlocker();
 
-  if (groupId != null) {
-    const relevantTabGroupChoice = tabGroupChoices[groupId];
-    if (
-      relevantTabGroupChoice != null &&
-      relevantTabGroupChoice !== selectedValue &&
-      values.some((value) => value.value === relevantTabGroupChoice)
-    ) {
-      setSelectedValue(relevantTabGroupChoice);
+  // Lazily restore the appropriate tab selected value
+  // We can't read queryString/localStorage on first render
+  // It would trigger a React SSR/client hydration mismatch
+  const restoreTabSelectedValue = useEvent(() => {
+    // wait for localStorage values to be set (initially empty object :s)
+    if (tabGroupChoicesReady) {
+      // querystring value > localStorage value
+      const valueToRestore =
+        tabQueryString.get() ?? (groupId && tabGroupChoices[groupId]);
+      const isValid =
+        valueToRestore &&
+        values.some((value) => value.value === valueToRestore);
+      if (isValid) {
+        setSelectedValue(valueToRestore);
+      }
     }
-  }
+  });
+  useEffect(() => {
+    // wait for localStorage values to be set (initially empty object :s)
+    if (tabGroupChoicesReady) {
+      restoreTabSelectedValue();
+    }
+  }, [tabGroupChoicesReady, restoreTabSelectedValue]);
 
   const handleTabChange = (
     event:
@@ -116,7 +193,7 @@ function TabsComponent(props: Props): JSX.Element {
     if (newTabValue !== selectedValue) {
       blockElementScrollPositionUntilNextRender(newTab);
       setSelectedValue(newTabValue);
-
+      tabQueryString.set(newTabValue);
       if (groupId != null) {
         setTabGroupChoices(groupId, String(newTabValue));
       }

package/src/theme-classic.d.ts

@@ -1263,6 +1263,7 @@ declare module '@theme/Tabs' {
     }[];
     readonly groupId?: string;
     readonly className?: string;
+    readonly queryString?: string | boolean;
   }
 
   export default function Tabs(props: Props): JSX.Element;